[SAMPLE-UPDATE] sample_grant_copy_auth

Chien Yuan Chang · Chien Yuan Chang · commit 39bc27b4053c · 2025-12-19T19:59:34.000-08:00
diff --git a/sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_grant_copy_auth_async.py b/sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_grant_copy_auth_async.py
@@ -9,17 +9,45 @@
 
 DESCRIPTION:
     This sample demonstrates how to grant copy authorization and copy an analyzer from a source
-    resource to a target resource (cross-resource copying). This is useful for copying analyzers
-    between different Azure resources or subscriptions.
+    Microsoft Foundry resource to a target Microsoft Foundry resource (cross-resource copying).
+    This is useful for copying analyzers between different Azure resources or subscriptions.
 
-    The grant_copy_authorization and copy_analyzer APIs allow you to copy an analyzer between
-    different Azure resources:
+ABOUT CROSS-RESOURCE COPYING:
+    The `grant_copy_authorization` and `copy_analyzer` APIs allow you to copy an analyzer
+    between different Azure resources:
     - Cross-resource copy: Copies an analyzer from one Azure resource to another
     - Authorization required: You must grant copy authorization before copying
-    - Use cases: Cross-subscription copying, resource migration, multi-region deployment
 
-    Note: For same-resource copying (copying within the same Azure resource), use the
-    sample_copy_analyzer_async.py sample instead.
+    When to use cross-resource copying:
+    - Copy between subscriptions: Move analyzers between different Azure subscriptions
+    - Multi-region deployment: Deploy the same analyzer to multiple regions
+    - Resource migration: Migrate analyzers from one resource to another
+    - Environment promotion: Promote analyzers from development to production across resources
+
+    Note: For same-resource copying (copying within the same Microsoft Foundry resource),
+    use the sample_copy_analyzer_async.py sample instead.
+
+PREREQUISITES:
+    To get started you'll need a **Microsoft Foundry resource**. For this cross-resource scenario,
+    you'll also need:
+    - Source Microsoft Foundry resource with model deployments configured
+    - Target Microsoft Foundry resource with model deployments configured
+    
+    Important: Both the source and target resources require the 'Cognitive Services User' role
+    to be granted to the credential used to run the code. This role is required for cross-resource
+    copying operations. Without this role, the grant_copy_authorization and copy_analyzer
+    operations will fail with authorization errors.
+
+HOW AUTHORIZATION WORKS:
+    The grant_copy_authorization method must be called on the source Microsoft Foundry resource
+    (where the analyzer currently exists). This is because the source resource needs to explicitly
+    grant permission for its analyzer to be copied. The method creates a time-limited authorization
+    record that grants permission to a specific target resource.
+
+    Where copy is performed: The copy_analyzer method must be called on the target Microsoft Foundry
+    resource (where the analyzer will be copied to). This is because the target resource is the one
+    receiving and creating the copy. When the target resource calls copy_analyzer, the service
+    validates that authorization was previously granted by the source resource.
 
 USAGE:
     python sample_grant_copy_auth_async.py
@@ -37,7 +65,8 @@
     Example resource ID format:
     /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{name}
 
-    Note: Both source and target AI Foundry Resources require 'Cognitive Services User' role for cross-subscription copy.
+    Important: Cross-resource copying requires credential-based authentication (such as DefaultAzureCredential).
+    API keys cannot be used for cross-resource operations.
 """
 
 import asyncio
@@ -100,7 +129,7 @@ async def main() -> None:
     target_resource_id = os.environ["AZURE_CONTENT_UNDERSTANDING_TARGET_RESOURCE_ID"]
     target_region = os.environ["AZURE_CONTENT_UNDERSTANDING_TARGET_REGION"]
 
-    # Create clients
+    # Create source and target clients using DefaultAzureCredential
     source_client = ContentUnderstandingClient(endpoint=source_endpoint, credential=source_credential)
     target_client = ContentUnderstandingClient(endpoint=target_endpoint, credential=target_credential)
 
@@ -120,34 +149,39 @@ async def main() -> None:
     try:
         async with source_client, target_client:
             # Step 1: Create the source analyzer
+            # The analyzer must exist in the source resource before it can be copied
             print(f"\nStep 1: Creating source analyzer '{source_analyzer_id}'...")
 
+            source_config = ContentAnalyzerConfig(
+                enable_formula=False,
+                enable_layout=True,
+                enable_ocr=True,
+                estimate_field_source_and_confidence=True,
+                return_details=True,
+            )
+
+            source_field_schema = ContentFieldSchema(
+                name="company_schema",
+                description="Schema for extracting company information",
+                fields={
+                    "company_name": ContentFieldDefinition(
+                        type=ContentFieldType.STRING,
+                        method=GenerationMethod.EXTRACT,
+                        description="Name of the company",
+                    ),
+                    "total_amount": ContentFieldDefinition(
+                        type=ContentFieldType.NUMBER,
+                        method=GenerationMethod.EXTRACT,
+                        description="Total amount on the document",
+                    ),
+                },
+            )
+
             source_analyzer = ContentAnalyzer(
                 base_analyzer_id="prebuilt-document",
                 description="Source analyzer for cross-resource copying",
-                config=ContentAnalyzerConfig(
-                    enable_formula=False,
-                    enable_layout=True,
-                    enable_ocr=True,
-                    estimate_field_source_and_confidence=True,
-                    return_details=True,
-                ),
-                field_schema=ContentFieldSchema(
-                    name="company_schema",
-                    description="Schema for extracting company information",
-                    fields={
-                        "company_name": ContentFieldDefinition(
-                            type=ContentFieldType.STRING,
-                            method=GenerationMethod.EXTRACT,
-                            description="Name of the company",
-                        ),
-                        "total_amount": ContentFieldDefinition(
-                            type=ContentFieldType.NUMBER,
-                            method=GenerationMethod.EXTRACT,
-                            description="Total amount on the document",
-                        ),
-                    },
-                ),
+                config=source_config,
+                field_schema=source_field_schema,
                 models={"completion": "gpt-4.1"},
             )
 
@@ -158,24 +192,36 @@ async def main() -> None:
             await poller.result()
             print(f"  Source analyzer created successfully!")
 
-            # Step 2: Grant copy authorization from source
-            # Grant authorization on the source client for copying to the target resource
+            # Step 2: Grant copy authorization
+            # Authorization must be granted by the source resource before the target resource can copy
+            # The grant_copy_authorization method takes:
+            # - The source analyzer ID to be copied
+            # - The target Azure resource ID that is allowed to receive the copy
+            # - The target region where the copy will be performed (optional, defaults to current region)
             print(f"\nStep 2: Granting copy authorization from source resource...")
+            print(f"  Target Azure Resource ID: {target_resource_id}")
+            print(f"  Target Region: {target_region}")
 
             copy_auth = await source_client.grant_copy_authorization(
                 analyzer_id=source_analyzer_id,
                 target_azure_resource_id=target_resource_id,
                 target_region=target_region,
             )
 
-            print(f"  Authorization granted!")
+            print(f"  Authorization granted successfully!")
             print(f"  Target Azure Resource ID: {copy_auth.target_azure_resource_id}")
             print(f"  Target Region: {target_region}")
             print(f"  Expires at: {copy_auth.expires_at}")
 
-            # Step 3: Copy analyzer using authorization
-            # Copy is performed on the target client, copying from source to target
+            # Step 3: Copy analyzer to target resource
+            # The copy_analyzer method must be called on the target client because the target
+            # resource is the one receiving and creating the copy. The target resource validates
+            # that authorization was previously granted by the source resource.
             print(f"\nStep 3: Copying analyzer from source to target...")
+            print(f"  Source Analyzer ID: {source_analyzer_id}")
+            print(f"  Source Azure Resource ID: {source_resource_id}")
+            print(f"  Source Region: {source_region}")
+            print(f"  Target Analyzer ID: {target_analyzer_id}")
 
             copy_poller = await target_client.begin_copy_analyzer(
                 analyzer_id=target_analyzer_id,
@@ -184,14 +230,16 @@ async def main() -> None:
                 source_region=source_region,
             )
             await copy_poller.result()
-            print(f"  Analyzer copied successfully!")
+            print(f"  Analyzer copied successfully to target resource!")
 
             # Step 4: Verify the copy
+            # Retrieve the analyzer from the target resource to verify the copy was successful
             print(f"\nStep 4: Verifying the copied analyzer...")
             copied_analyzer = await target_client.get_analyzer(analyzer_id=target_analyzer_id)
             print(f"  Target Analyzer ID: {copied_analyzer.analyzer_id}")
             print(f"  Description: {copied_analyzer.description}")
             print(f"  Status: {copied_analyzer.status}")
+            print(f"\nCross-resource copy completed successfully!")
 
     finally:
         # Clean up - create new client instances for cleanup since the original ones are closed
diff --git a/sdk/contentunderstanding/azure-ai-contentunderstanding/samples/sample_grant_copy_auth.py b/sdk/contentunderstanding/azure-ai-contentunderstanding/samples/sample_grant_copy_auth.py
@@ -9,17 +9,45 @@
 
 DESCRIPTION:
     This sample demonstrates how to grant copy authorization and copy an analyzer from a source
-    resource to a target resource (cross-resource copying). This is useful for copying analyzers
-    between different Azure resources or subscriptions.
+    Microsoft Foundry resource to a target Microsoft Foundry resource (cross-resource copying).
+    This is useful for copying analyzers between different Azure resources or subscriptions.
 
-    The grant_copy_authorization and copy_analyzer APIs allow you to copy an analyzer between
-    different Azure resources:
+ABOUT CROSS-RESOURCE COPYING:
+    The `grant_copy_authorization` and `copy_analyzer` APIs allow you to copy an analyzer
+    between different Azure resources:
     - Cross-resource copy: Copies an analyzer from one Azure resource to another
     - Authorization required: You must grant copy authorization before copying
-    - Use cases: Cross-subscription copying, resource migration, multi-region deployment
 
-    Note: For same-resource copying (copying within the same Azure resource), use the
-    sample_copy_analyzer.py sample instead.
+    When to use cross-resource copying:
+    - Copy between subscriptions: Move analyzers between different Azure subscriptions
+    - Multi-region deployment: Deploy the same analyzer to multiple regions
+    - Resource migration: Migrate analyzers from one resource to another
+    - Environment promotion: Promote analyzers from development to production across resources
+
+    Note: For same-resource copying (copying within the same Microsoft Foundry resource),
+    use the sample_copy_analyzer.py sample instead.
+
+PREREQUISITES:
+    To get started you'll need a **Microsoft Foundry resource**. For this cross-resource scenario,
+    you'll also need:
+    - Source Microsoft Foundry resource with model deployments configured
+    - Target Microsoft Foundry resource with model deployments configured
+    
+    Important: Both the source and target resources require the 'Cognitive Services User' role
+    to be granted to the credential used to run the code. This role is required for cross-resource
+    copying operations. Without this role, the grant_copy_authorization and copy_analyzer
+    operations will fail with authorization errors.
+
+HOW AUTHORIZATION WORKS:
+    The grant_copy_authorization method must be called on the source Microsoft Foundry resource
+    (where the analyzer currently exists). This is because the source resource needs to explicitly
+    grant permission for its analyzer to be copied. The method creates a time-limited authorization
+    record that grants permission to a specific target resource.
+
+    Where copy is performed: The copy_analyzer method must be called on the target Microsoft Foundry
+    resource (where the analyzer will be copied to). This is because the target resource is the one
+    receiving and creating the copy. When the target resource calls copy_analyzer, the service
+    validates that authorization was previously granted by the source resource.
 
 USAGE:
     python sample_grant_copy_auth.py
@@ -37,7 +65,8 @@
     Example resource ID format:
     /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{name}
 
-    Note: Both source and target AI Foundry Resources require 'Cognitive Services User' role for cross-subscription copy.
+    Important: Cross-resource copying requires credential-based authentication (such as DefaultAzureCredential).
+    API keys cannot be used for cross-resource operations.
 """
 
 import os
@@ -99,7 +128,7 @@ def main() -> None:
     target_resource_id = os.environ["AZURE_CONTENT_UNDERSTANDING_TARGET_RESOURCE_ID"]
     target_region = os.environ["AZURE_CONTENT_UNDERSTANDING_TARGET_REGION"]
 
-    # Create clients
+    # Create source and target clients using DefaultAzureCredential
     source_client = ContentUnderstandingClient(endpoint=source_endpoint, credential=source_credential)
     target_client = ContentUnderstandingClient(endpoint=target_endpoint, credential=target_credential)
 
@@ -118,34 +147,39 @@ def main() -> None:
 
     try:
         # Step 1: Create the source analyzer
+        # The analyzer must exist in the source resource before it can be copied
         print(f"\nStep 1: Creating source analyzer '{source_analyzer_id}'...")
 
+        source_config = ContentAnalyzerConfig(
+            enable_formula=False,
+            enable_layout=True,
+            enable_ocr=True,
+            estimate_field_source_and_confidence=True,
+            return_details=True,
+        )
+
+        source_field_schema = ContentFieldSchema(
+            name="company_schema",
+            description="Schema for extracting company information",
+            fields={
+                "company_name": ContentFieldDefinition(
+                    type=ContentFieldType.STRING,
+                    method=GenerationMethod.EXTRACT,
+                    description="Name of the company",
+                ),
+                "total_amount": ContentFieldDefinition(
+                    type=ContentFieldType.NUMBER,
+                    method=GenerationMethod.EXTRACT,
+                    description="Total amount on the document",
+                ),
+            },
+        )
+
         source_analyzer = ContentAnalyzer(
             base_analyzer_id="prebuilt-document",
             description="Source analyzer for cross-resource copying",
-            config=ContentAnalyzerConfig(
-                enable_formula=False,
-                enable_layout=True,
-                enable_ocr=True,
-                estimate_field_source_and_confidence=True,
-                return_details=True,
-            ),
-            field_schema=ContentFieldSchema(
-                name="company_schema",
-                description="Schema for extracting company information",
-                fields={
-                    "company_name": ContentFieldDefinition(
-                        type=ContentFieldType.STRING,
-                        method=GenerationMethod.EXTRACT,
-                        description="Name of the company",
-                    ),
-                    "total_amount": ContentFieldDefinition(
-                        type=ContentFieldType.NUMBER,
-                        method=GenerationMethod.EXTRACT,
-                        description="Total amount on the document",
-                    ),
-                },
-            ),
+            config=source_config,
+            field_schema=source_field_schema,
             models={"completion": "gpt-4.1"},
         )
 
@@ -156,24 +190,36 @@ def main() -> None:
         poller.result()
         print(f"  Source analyzer created successfully!")
 
-        # Step 2: Grant copy authorization from source
-        # Grant authorization on the source client for copying to the target resource
+        # Step 2: Grant copy authorization
+        # Authorization must be granted by the source resource before the target resource can copy
+        # The grant_copy_authorization method takes:
+        # - The source analyzer ID to be copied
+        # - The target Azure resource ID that is allowed to receive the copy
+        # - The target region where the copy will be performed (optional, defaults to current region)
         print(f"\nStep 2: Granting copy authorization from source resource...")
+        print(f"  Target Azure Resource ID: {target_resource_id}")
+        print(f"  Target Region: {target_region}")
 
         copy_auth = source_client.grant_copy_authorization(
             analyzer_id=source_analyzer_id,
             target_azure_resource_id=target_resource_id,
             target_region=target_region,
         )
 
-        print(f"  Authorization granted!")
+        print(f"  Authorization granted successfully!")
         print(f"  Target Azure Resource ID: {copy_auth.target_azure_resource_id}")
         print(f"  Target Region: {target_region}")
         print(f"  Expires at: {copy_auth.expires_at}")
 
-        # Step 3: Copy analyzer using authorization
-        # Copy is performed on the target client, copying from source to target
+        # Step 3: Copy analyzer to target resource
+        # The copy_analyzer method must be called on the target client because the target
+        # resource is the one receiving and creating the copy. The target resource validates
+        # that authorization was previously granted by the source resource.
         print(f"\nStep 3: Copying analyzer from source to target...")
+        print(f"  Source Analyzer ID: {source_analyzer_id}")
+        print(f"  Source Azure Resource ID: {source_resource_id}")
+        print(f"  Source Region: {source_region}")
+        print(f"  Target Analyzer ID: {target_analyzer_id}")
 
         copy_poller = target_client.begin_copy_analyzer(
             analyzer_id=target_analyzer_id,
@@ -182,17 +228,19 @@ def main() -> None:
             source_region=source_region,
         )
         copy_poller.result()
-        print(f"  Analyzer copied successfully!")
+        print(f"  Analyzer copied successfully to target resource!")
 
         # Step 4: Verify the copy
+        # Retrieve the analyzer from the target resource to verify the copy was successful
         print(f"\nStep 4: Verifying the copied analyzer...")
         copied_analyzer = target_client.get_analyzer(analyzer_id=target_analyzer_id)
         print(f"  Target Analyzer ID: {copied_analyzer.analyzer_id}")
         print(f"  Description: {copied_analyzer.description}")
         print(f"  Status: {copied_analyzer.status}")
+        print(f"\nCross-resource copy completed successfully!")
 
     finally:
-        # Clean up
+        # Clean up: Delete both source and target analyzers
         print(f"\nCleaning up...")
         try:
             source_client.delete_analyzer(analyzer_id=source_analyzer_id)
