Add importProperties parameter for selective property import and improve state tracking

[RudyBricks]

Overview

This PR enhances the import functionality for msgraph_resource to support importing existing Microsoft Graph resources without triggering unintended modifications (see #89). It introduces the importProperties query parameter and improves state management for more accurate drift detection.

Changes

1. Import with Selective Properties (importProperties)

• Feature: Added support for importProperties query parameter in import operations
• Purpose: Allows users to specify which properties to track when importing existing resources
• Syntax: /groups/{id}?importProperties=displayName,mailEnabled,mailNickname,securityEnabled
• Behavior:
  • Seeds specified properties as null in Terraform state during import
  • Subsequent Read operation populates them with actual values from Microsoft Graph
  • Enables managing only selected properties while ignoring others
  • Supports nested properties using dot notation (e.g., web.redirectUris)

2. Enhanced State Management

• Remote State Tracking: Always save the remote resource state into private state during Read operations
• Improved PATCH Calculation: Calculate PATCH body by comparing against the remote state stored in private state instead of the Terraform state
• Benefits:
  • More accurate drift detection
  • Prevents unnecessary updates when properties haven't actually changed
  • Better handling of properties that may be modified outside Terraform

3. Comprehensive Documentation

• Updated docs/resources/resource.md with detailed import examples
• Updated docs/resources/groups.md with group-specific import patterns
• Created new comprehensive guide: docs/guides/importing_resources.md
• Added example workflow in examples/imports/groups/
• Documented best practices, common patterns, and troubleshooting

Use Case

This is particularly valuable when importing existing Microsoft Graph resources into Terraform management:

Before: Importing a resource would result in an empty body, causing Terraform to want to remove all properties on the next plan.

After: Users can selectively import properties they want to manage:

terraform import msgraph_resource.group "/groups/{id}?importProperties=displayName,mailEnabled,mailNickname,securityEnabled"

[RudyBricks]

@microsoft-github-policy-service agree

[RudyBricks]

@ms-henglu anything I can do to make the review easier for you?