Add importProperties parameter for selective property import

[RudyBricks]

Overview

This PR enhances the import functionality for msgraph_resource so that existing Microsoft Graph resources can be imported without triggering unintended modifications (Fixes #89). It introduces the importProperties query parameter, which lets users declare exactly which properties Terraform should manage.

Note: an earlier revision of this branch also changed how the PATCH body is calculated (diffing against the remote response saved in private state). That work has been split out into a separate branch so this PR stays scoped to the import mechanism.

Changes

1. Import with selective properties (importProperties)

• Feature: added support for an importProperties query parameter in import IDs
• Purpose: lets users specify which properties to track when importing an existing resource
• Syntax: /groups/{id}?importProperties=displayName,mailEnabled,mailNickname,securityEnabled
• Behavior:
  • Seeds the named properties as null in state during import
  • The subsequent Read populates them with the actual values from Microsoft Graph
  • Only the named properties are managed; everything else is left alone
  • Nested properties are supported via dot notation (e.g. web.redirectUris)
  • When a property and one of its children are both named, the more specific path wins regardless of the order they appear in, so web,web.redirectUris and web.redirectUris,web seed the same body
  • Paths with empty segments (web..redirectUris, web., .web) are skipped without affecting the remaining properties

ImportState performs no API calls — it parses the import ID and seeds state, and the values are filled in by the following Read.

2. Tests

Added internal/services/import_properties_test.go — 21 table-driven cases, no credentials or network required:

• TestAddNullProperty covers flat, nested and deep paths, shared parents, duplicates, all three parent/child collision orderings, and malformed paths
• TestImportStateBody drives ImportState end to end and asserts body, url, id and api_version for: no query parameter, single and nested properties, whitespace trimming, empty and separator-only values, api-version=beta combined with importProperties, and $ref imports

3. Documentation

• New guide: docs/guides/importing_resources.md (and its templates/ source), covering the workflow, nested and overlapping property paths, API versions, $ref relationships, best practices and troubleshooting
• Updated docs/resources/resource.md with import examples
• New worked example under examples/imports/groups/

Use case

Before: importing a resource left body null. On the next plan Terraform saw every configured property as missing from state and proposed an in-place update, sending a redundant PATCH that rewrote properties which already held the correct values:

  ~ resource "msgraph_resource" "group" {
      + body = {
          + displayName     = "My Group"
          + mailEnabled     = false
        }
    }

Plan: 1 to import, 0 to add, 1 to change, 0 to destroy.

After: users import exactly the properties they intend to manage, and the first plan is clean:

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

Plan: 1 to import, 0 to add, 0 to change, 0 to destroy.

Verification

Besides the unit tests, the workflow was exercised against a live tenant using the example in examples/imports/groups/:

Scenario	Result
Config matches remote, with importProperties	0 to change; follow-up plan reports no changes
Config matches remote, without importProperties	1 to change — the behaviour being fixed
Config differs on one managed property	1 to change, scoped to that property alone
Property set remotely but named in neither body nor importProperties	0 to change; never enters state

[RudyBricks]

@microsoft-github-policy-service agree

[RudyBricks]

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