[DI] Add samples and update README

sdk/documentintelligence/azure-ai-documentintelligence/README.md

@@ -12,8 +12,14 @@ Azure AI Document Intelligence ([previously known as Form Recognizer][service-re
 
 [Source code][python-di-src]
 | [Package (PyPI)][python-di-pypi]
+| [API reference documentation][python-di-ref-docs]
+| [Product documentation][python-di-product-docs]
 | [Samples][python-di-samples]
 
+## _Disclaimer_
+
+_The API version 2024-02-29-preview is currently only available in some Azure regions, the available regions can be found from [here][python-di-available-regions]._
+
 ## Getting started
 
 ### Installating the package
@@ -679,7 +685,12 @@ additional questions or comments.
 [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
 [default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential
 [azure_sub]: https://azure.microsoft.com/free/
-[python-di-product-docs]: https://learn.microsoft.com/azure/applied-ai-services/form-recognizer/overview?view=form-recog-3.0.0
+[python-di-src]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/azure/ai/documentintelligence
+[python-di-pypi]: https://pypi.org/project/azure-ai-documentintelligence/
+[python-di-product-docs]: https://learn.microsoft.com/azure/ai-services/document-intelligence/overview?view=doc-intel-4.0.0&viewFallbackFrom=form-recog-3.0.0
+[python-di-ref-docs]: https://aka.ms/azsdk/python/documentintelligence/docs
+[python-di-samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/samples
+[python-di-available-regions]: https://aka.ms/azsdk/documentintelligence/available-regions
 [azure_portal]: https://ms.portal.azure.com/
 [regional_endpoints]: https://azure.microsoft.com/global-infrastructure/services/?products=form-recognizer
 [cognitive_resource_portal]: https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer

sdk/documentintelligence/azure-ai-documentintelligence/samples/aio/sample_convert_to_dict_async.py

@@ -0,0 +1,91 @@
+# coding: utf-8
+
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+"""
+FILE: sample_convert_to_dict_async.py
+
+DESCRIPTION:
+    This sample demonstrates how to convert a model returned from an analyze operation
+    to a JSON serializable dictionary.
+
+USAGE:
+    python sample_convert_to_dict_async.py
+
+    Set the environment variables with your own values before running the sample:
+    1) DOCUMENTINTELLIGENCE_ENDPOINT - the endpoint to your Document Intelligence resource.
+    2) DOCUMENTINTELLIGENCE_API_KEY - your Document Intelligence API key
+"""
+
+import os
+import json
+import asyncio
+
+
+async def convert_to_and_from_dict_async():
+    path_to_sample_documents = os.path.abspath(
+        os.path.join(
+            os.path.abspath(__file__),
+            "..",
+            "..",
+            "./sample_forms/forms/Form_1.jpg",
+        )
+    )
+
+    from azure.core.credentials import AzureKeyCredential
+    from azure.ai.documentintelligence.aio import DocumentIntelligenceClient
+    from azure.ai.documentintelligence.models import AnalyzeResult
+
+    endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
+    key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]
+
+    document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))
+    async with document_intelligence_client:
+        with open(path_to_sample_documents, "rb") as f:
+            poller = await document_intelligence_client.begin_analyze_document(
+                "prebuilt-layout", analyze_request=f, content_type="application/octet-stream"
+            )
+        result: AnalyzeResult = await poller.result()
+
+    # convert the received model to a dictionary
+    analyze_result_dict = result.as_dict()
+
+    # save the dictionary as JSON content in a JSON file.
+    with open("data.json", "w") as output_file:
+        json.dump(analyze_result_dict, output_file, indent=4)
+
+
+async def main():
+    await convert_to_and_from_dict_async()
+
+
+if __name__ == "__main__":
+    from azure.core.exceptions import HttpResponseError
+    from dotenv import find_dotenv, load_dotenv
+
+    try:
+        load_dotenv(find_dotenv())
+        asyncio.run(main())
+    except HttpResponseError as error:
+        print(
+            "For more information about troubleshooting errors, see the following guide: "
+            "https://aka.ms/azsdk/python/formrecognizer/troubleshooting"
+        )
+        # Examples of how to check an HttpResponseError
+        # Check by error code:
+        if error.error is not None:
+            if error.error.code == "InvalidImage":
+                print(f"Received an invalid image error: {error.error}")
+            if error.error.code == "InvalidRequest":
+                print(f"Received an invalid request error: {error.error}")
+            # Raise the error again after printing it
+            raise
+        # If the inner error is None and then it is possible to check the message to get more information:
+        if "Invalid request".casefold() in error.message.casefold():
+            print(f"Uh-oh! Seems there was an invalid request: {error}")
+        # Raise the error again
+        raise

sdk/documentintelligence/azure-ai-documentintelligence/samples/aio/sample_copy_model_to_async.py

@@ -10,17 +10,17 @@
 FILE: sample_copy_model_to_async.py
 
 DESCRIPTION:
-    This sample demonstrates how to copy a custom model from a source Form Recognizer resource
-    to a target Form Recognizer resource.
+    This sample demonstrates how to copy a custom model from a source Document Intelligence resource
+    to a target Document Intelligence resource.
 
 USAGE:
     python sample_copy_model_to_async.py
 
     Set the environment variables with your own values before running the sample:
     1) DOCUMENTINTELLIGENCE_ENDPOINT - the endpoint to your Document Intelligence resource.
     2) DOCUMENTINTELLIGENCE_API_KEY - your Document Intelligence API key.
-    3) DOCUMENTINTELLIGENCE_TARGET_ENDPOINT - the endpoint to your target Form Recognizer resource.
-    4) DOCUMENTINTELLIGENCE_TARGET_API_KEY - your target Form Recognizer API key
+    3) DOCUMENTINTELLIGENCE_TARGET_ENDPOINT - the endpoint to your target Document Intelligence resource.
+    4) DOCUMENTINTELLIGENCE_TARGET_API_KEY - your target Document Intelligence API key
     5) AZURE_SOURCE_MODEL_ID - the model ID from the source resource to be copied over to the target resource.
         - OR -
        DOCUMENTINTELLIGENCE_STORAGE_CONTAINER_SAS_URL - The shared access signature (SAS) Url of your Azure Blob Storage container with your training files.

sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_convert_to_dict.py

@@ -0,0 +1,84 @@
+# coding: utf-8
+
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+"""
+FILE: sample_convert_to_dict.py
+
+DESCRIPTION:
+    This sample demonstrates how to convert a model returned from an analyze operation
+    to a JSON serializable dictionary.
+
+USAGE:
+    python sample_convert_to_dict.py
+
+    Set the environment variables with your own values before running the sample:
+    1) DOCUMENTINTELLIGENCE_ENDPOINT - the endpoint to your Document Intelligence resource.
+    2) DOCUMENTINTELLIGENCE_API_KEY - your Document Intelligence API key
+"""
+
+import os
+import json
+
+
+def convert_to_and_from_dict():
+    path_to_sample_documents = os.path.abspath(
+        os.path.join(
+            os.path.abspath(__file__),
+            "..",
+            "./sample_forms/forms/Form_1.jpg",
+        )
+    )
+
+    from azure.core.credentials import AzureKeyCredential
+    from azure.ai.documentintelligence import DocumentIntelligenceClient
+    from azure.ai.documentintelligence.models import AnalyzeResult
+
+    endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
+    key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]
+
+    document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))
+    with open(path_to_sample_documents, "rb") as f:
+        poller = document_intelligence_client.begin_analyze_document(
+            "prebuilt-layout", analyze_request=f, content_type="application/octet-stream"
+        )
+    result: AnalyzeResult = poller.result()
+
+    # convert the received model to a dictionary
+    analyze_result_dict = result.as_dict()
+
+    # save the dictionary as JSON content in a JSON file
+    with open("data.json", "w") as output_file:
+        json.dump(analyze_result_dict, output_file, indent=4)
+
+
+if __name__ == "__main__":
+    from azure.core.exceptions import HttpResponseError
+    from dotenv import find_dotenv, load_dotenv
+
+    try:
+        load_dotenv(find_dotenv())
+        convert_to_and_from_dict()
+    except HttpResponseError as error:
+        print(
+            "For more information about troubleshooting errors, see the following guide: "
+            "https://aka.ms/azsdk/python/formrecognizer/troubleshooting"
+        )
+        # Examples of how to check an HttpResponseError
+        # Check by error code:
+        if error.error is not None:
+            if error.error.code == "InvalidImage":
+                print(f"Received an invalid image error: {error.error}")
+            if error.error.code == "InvalidRequest":
+                print(f"Received an invalid request error: {error.error}")
+            # Raise the error again after printing it
+            raise
+        # If the inner error is None and then it is possible to check the message to get more information:
+        if "Invalid request".casefold() in error.message.casefold():
+            print(f"Uh-oh! Seems there was an invalid request: {error}")
+        # Raise the error again
+        raise

sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_copy_model_to.py

@@ -10,17 +10,17 @@
 FILE: sample_copy_model_to.py
 
 DESCRIPTION:
-    This sample demonstrates how to copy a custom model from a source Form Recognizer resource
-    to a target Form Recognizer resource.
+    This sample demonstrates how to copy a custom model from a source Document Intelligence resource
+    to a target Document Intelligence resource.
 
 USAGE:
     python sample_copy_model_to.py
 
     Set the environment variables with your own values before running the sample:
     1) DOCUMENTINTELLIGENCE_ENDPOINT - the endpoint to your Document Intelligence resource.
     2) DOCUMENTINTELLIGENCE_API_KEY - your Document Intelligence API key.
-    3) DOCUMENTINTELLIGENCE_TARGET_ENDPOINT - the endpoint to your target Form Recognizer resource.
-    4) DOCUMENTINTELLIGENCE_TARGET_API_KEY - your target Form Recognizer API key
+    3) DOCUMENTINTELLIGENCE_TARGET_ENDPOINT - the endpoint to your target Document Intelligence resource.
+    4) DOCUMENTINTELLIGENCE_TARGET_API_KEY - your target Document Intelligence API key
     5) AZURE_SOURCE_MODEL_ID - the model ID from the source resource to be copied over to the target resource.
         - OR -
        DOCUMENTINTELLIGENCE_STORAGE_CONTAINER_SAS_URL - The shared access signature (SAS) Url of your Azure Blob Storage container with your training files.