add using api key

Author: chienyuanchang

README.md

@@ -71,7 +71,7 @@ Once you click the link above, please follow the steps below to set up the Codes
 ## Configure Azure AI service resource
 ### (Option 1) Use `azd` commands to auto create temporal resources to run sample
 1. Make sure you have permission to grant roles under subscription
-1. Login Azure
+2. Login Azure
     ```shell
     azd auth login
     ```
@@ -80,12 +80,11 @@ Once you click the link above, please follow the steps below to set up the Codes
     azd auth login --use-device-code
     ```
 
-1. Setting up environment, following prompts to choose location
+3. Setting up environment, following prompts to choose location
     ```shell
     azd up
     ```
 
-
 ### (Option 2) Manually create resources and set environment variables
 1. Create [Azure AI Services resource](docs/create_azure_ai_service.md)
 2. Go to `Access Control (IAM)` in resource, grant yourself role `Cognitive Services User`
@@ -97,6 +96,20 @@ Once you click the link above, please follow the steps below to set up the Codes
    azd auth login
    ```
 
+### (Option 3) Use Endpoint and Key (No `azd` Required)
+1. Create [Azure AI Services resource](docs/create_azure_ai_service.md)
+2. Copy `notebooks/.env.sample` to `notebooks/.env`
+    ```bash
+    cp notebooks/.env.sample notebooks/.env
+    ```
+3. Update `.env` with your credentials
+    - Edit notebooks/.env and set the following values:
+      ```
+      AZURE_AI_ENDPOINT=https://<your-resource-name>.services.ai.azure.com/
+      AZURE_AI_API_KEY=<your-azure-ai-api-key>
+      ```
+    - Replace <your-resource-name> and <your-azure-ai-api-key> with your actual values. You can find them in your AI Services resource under `Resource Management`/`Keys and Endpoint`
+
 ## Open a Jupyter notebook and follow the step-by-step guidance
 
 Navigate to the `notebooks` directory and select the sample notebook you are interested in. Since the Dev Container (in Codespaces or in your local enviornment) is pre-configured with the necessary environment, you can directly execute each step in the notebook.

notebooks/analyzer_training.ipynb

@@ -60,7 +60,12 @@
    "metadata": {},
    "source": [
     "## Create Azure content understanding client\n",
-    ">The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is utility Class which contain the functions to interact with the Content Understanding server. Before Content Understanding SDK release, we can regard it as a lightweight SDK. Fill the constant **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, **AZURE_AI_API_KEY** with the information from your Azure AI Service."
+    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is utility Class which contain the functions to interact with the Content Understanding server. Before Content Understanding SDK release, we can regard it as a lightweight SDK. Fill the constant **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, **AZURE_AI_API_KEY** with the information from your Azure AI Service.\n",
+    "\n",
+    "> ⚠️ Important:\n",
+    "You must update the code below to match your Azure authentication method.\n",
+    "Look for the `# IMPORTANT` comments and modify those sections accordingly.\n",
+    "If you skip this step, the sample may not run correctly."
    ]
   },
   {
@@ -91,7 +96,10 @@
     "client = AzureContentUnderstandingClient(\n",
     "    endpoint=os.getenv(\"AZURE_AI_ENDPOINT\"),\n",
     "    api_version=os.getenv(\"AZURE_AI_API_VERSION\", \"2025-05-01-preview\"),\n",
+    "    # IMPORTANT: Comment out token_provider if using subscription key\n",
     "    token_provider=token_provider,\n",
+    "    # IMPORTANT: Uncomment this if using subscription key\n",
+    "    # subscription_key=os.getenv(\"AZURE_AI_API_KEY\"),\n",
     "    x_ms_useragent=\"azure-ai-content-understanding-python/analyzer_training\", # This header is used for sample usage telemetry, please comment out this line if you want to opt out.\n",
     ")"
    ]

notebooks/build_person_directory.ipynb

@@ -28,7 +28,12 @@
    "metadata": {},
    "source": [
     "## Create Azure content understanding face client\n",
-    ">The [AzureContentUnderstandingFaceClient](../python/content_understanding_face_client.py) is a utility class for interacting with the Content Understanding Face service. Before the official SDK is released, this acts as a lightweight SDK. Set the constants **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, and **AZURE_AI_API_KEY** with your Azure AI Service information."
+    "> The [AzureContentUnderstandingFaceClient](../python/content_understanding_face_client.py) is a utility class for interacting with the Content Understanding Face service. Before the official SDK is released, this acts as a lightweight SDK. Set the constants **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, and **AZURE_AI_API_KEY** with your Azure AI Service information.\n",
+    "\n",
+    "> ⚠️ Important:\n",
+    "You must update the code below to match your Azure authentication method.\n",
+    "Look for the `# IMPORTANT` comments and modify those sections accordingly.\n",
+    "If you skip this step, the sample may not run correctly."
    ]
   },
   {
@@ -59,7 +64,10 @@
     "client = AzureContentUnderstandingFaceClient(\n",
     "    endpoint=os.getenv(\"AZURE_AI_ENDPOINT\"),\n",
     "    api_version=os.getenv(\"AZURE_AI_API_VERSION\", \"2025-05-01-preview\"),\n",
+    "    # IMPORTANT: Comment out token_provider if using subscription key\n",
     "    token_provider=token_provider,\n",
+    "    # IMPORTANT: Uncomment this if using subscription key\n",
+    "    # subscription_key=os.getenv(\"AZURE_AI_API_KEY\"),\n",
     "    x_ms_useragent=\"azure-ai-content-understanding-python/build_person_directory\", # This header is used for sample usage telemetry, please comment out this line if you want to opt out.\n",
     ")"
    ]

notebooks/classifier.ipynb

@@ -93,7 +93,7 @@
     "\n",
     "- **AZURE_AI_ENDPOINT**: Your Azure AI service endpoint URL or set up in \".env\" file\n",
     "- **AZURE_AI_API_VERSION**: The Azure AI API version to use. Default is \"2025-05-01-preview\". \n",
-    "- **SUBSCRIPTION_KEY**: Your subscription key (optional if using token authentication)\n",
+    "- **AZURE_AI_API_KEY**: Your Azure AI service key (optional if using token authentication)\n",
     "- **ANALYZER_SAMPLE_FILE**: Path to the PDF document you want to process"
    ]
   },
@@ -103,13 +103,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# For authentication, you can use either token-based auth or subscription key, and only one of them is required\n",
     "AZURE_AI_ENDPOINT = os.getenv(\"AZURE_AI_ENDPOINT\")\n",
+    "# IMPORTANT: Replace with your actual subscription key or set up in \".env\" file if not using token auth\n",
+    "AZURE_AI_API_KEY = os.getenv(\"AZURE_AI_API_KEY\")\n",
     "AZURE_AI_API_VERSION = os.getenv(\"AZURE_AI_API_VERSION\", \"2025-05-01-preview\")\n",
-    "ANALYZER_SAMPLE_FILE = \"../data/MS_Annual_Report_2024.pdf\" # Update this path to your PDF file\n",
-    "\n",
-    "# For authentication, you can use either token-based auth or subscription key, and only one of them is required\n",
-    "# IMPORTANT: Replace with your actual subscription key if not using token auth\n",
-    "SUBSCRIPTION_KEY = \"dummy_key\"\n",
+    "ANALYZER_SAMPLE_FILE = \"../data/MS_Annual_Report_2024.pdf\"  # Update this path to your PDF file\n",
     "\n",
     "# Authentication - Using DefaultAzureCredential for token-based auth\n",
     "credential = DefaultAzureCredential()\n",
@@ -165,7 +164,7 @@
     "            \"description\": \"Annual meeting details, stock information, and shareholder services.\"\n",
     "        }\n",
     "    },\n",
-    "    \"splitMode\": \"auto\"  # IMPORTANT: Automatically detect document boundaries\n",
+    "    \"splitMode\": \"auto\"  # IMPORTANT: Automatically detect document boundaries. Can change mode for your needs.\n",
     "}\n",
     "\n",
     "print(\"📄 Classifier Categories:\")\n",
@@ -201,7 +200,7 @@
     "        # IMPORTANT: Comment out token_provider if using subscription key\n",
     "        token_provider=token_provider,\n",
     "        # IMPORTANT: Uncomment this if using subscription key\n",
-    "        # subscription_key=SUBSCRIPTION_KEY\n",
+    "        # subscription_key=AZURE_AI_API_KEY,\n",
     "    )\n",
     "    print(\"✅ Content Understanding client initialized successfully!\")\n",
     "    print(\"   Ready to create classifiers and analyzers.\")\n",
@@ -432,7 +431,7 @@
     "        },\n",
     "        \"Annual Report\": {\n",
     "            \"description\": \"Each document must ends with 'end of encounter'. Dont rely on page numbers\",\n",
-    "            \"analyzerId\": analyzer_id  # IMPORTANT: Use our custom analyzer for annual reports\n",
+    "            \"analyzerId\": analyzer_id  # IMPORTANT: Use created custom analyzer in previous step for annual reports\n",
     "        },\n",
     "        \"Declaration_of_custodian\": {\n",
     "            \"description\": \"Declarations of custodian documents, often used in legal contexts.\"\n",

notebooks/content_extraction.ipynb

@@ -38,7 +38,12 @@
    "source": [
     "## Create Azure AI Content Understanding Client\n",
     "\n",
-    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK.\n"
+    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK. Fill the constant **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, **AZURE_AI_API_KEY** with the information from your Azure AI Service.\n",
+    "\n",
+    "> ⚠️ Important:\n",
+    "You must update the code below to match your Azure authentication method.\n",
+    "Look for the `# IMPORTANT` comments and modify those sections accordingly.\n",
+    "If you skip this step, the sample may not run correctly."
    ]
   },
   {
@@ -59,7 +64,10 @@
     "load_dotenv(find_dotenv())\n",
     "logging.basicConfig(level=logging.INFO)\n",
     "\n",
+    "# For authentication, you can use either token-based auth or subscription key, and only one of them is required\n",
     "AZURE_AI_ENDPOINT = os.getenv(\"AZURE_AI_ENDPOINT\")\n",
+    "# IMPORTANT: Replace with your actual subscription key or set up in \".env\" file if not using token auth\n",
+    "AZURE_AI_API_KEY = os.getenv(\"AZURE_AI_API_KEY\")\n",
     "AZURE_AI_API_VERSION = os.getenv(\"AZURE_AI_API_VERSION\", \"2025-05-01-preview\")\n",
     "\n",
     "# Add the parent directory to the path to use shared modules\n",
@@ -73,7 +81,10 @@
     "client = AzureContentUnderstandingClient(\n",
     "    endpoint=AZURE_AI_ENDPOINT,\n",
     "    api_version=AZURE_AI_API_VERSION,\n",
+    "    # IMPORTANT: Comment out token_provider if using subscription key\n",
     "    token_provider=token_provider,\n",
+    "    # IMPORTANT: Uncomment this if using subscription key\n",
+    "    # subscription_key=AZURE_AI_API_KEY,\n",
     "    x_ms_useragent=\"azure-ai-content-understanding-python/content_extraction\", # This header is used for sample usage telemetry, please comment out this line if you want to opt out.\n",
     ")\n",
     "\n",

notebooks/conversational_field_extraction.ipynb

@@ -88,7 +88,12 @@
    "source": [
     "## Create Azure AI Content Understanding Client\n",
     "\n",
-    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK.\n"
+    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK. Fill the constant **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, **AZURE_AI_API_KEY** with the information from your Azure AI Service.\n",
+    "\n",
+    "> ⚠️ Important:\n",
+    "You must update the code below to match your Azure authentication method.\n",
+    "Look for the `# IMPORTANT` comments and modify those sections accordingly.\n",
+    "If you skip this step, the sample may not run correctly."
    ]
   },
   {
@@ -108,7 +113,10 @@
     "load_dotenv(find_dotenv())\n",
     "logging.basicConfig(level=logging.INFO)\n",
     "\n",
+    "# For authentication, you can use either token-based auth or subscription key, and only one of them is required\n",
     "AZURE_AI_ENDPOINT = os.getenv(\"AZURE_AI_ENDPOINT\")\n",
+    "# IMPORTANT: Replace with your actual subscription key or set up in \".env\" file if not using token auth\n",
+    "AZURE_AI_API_KEY = os.getenv(\"AZURE_AI_API_KEY\")\n",
     "AZURE_AI_API_VERSION = os.getenv(\"AZURE_AI_API_VERSION\", \"2025-05-01-preview\")\n",
     "\n",
     "# Add the parent directory to the path to use shared modules\n",
@@ -122,7 +130,10 @@
     "client = AzureContentUnderstandingClient(\n",
     "    endpoint=AZURE_AI_ENDPOINT,\n",
     "    api_version=AZURE_AI_API_VERSION,\n",
+    "    # IMPORTANT: Comment out token_provider if using subscription key\n",
     "    token_provider=token_provider,\n",
+    "    # IMPORTANT: Uncomment this if using subscription key\n",
+    "    # subscription_key=AZURE_AI_API_KEY,\n",
     "    # x_ms_useragent=\"azure-ai-content-understanding-python/field_extraction\", # This header is used for sample usage telemetry, please comment out this line if you want to opt out.\n",
     ")"
    ]

notebooks/field_extraction.ipynb

@@ -98,7 +98,12 @@
    "source": [
     "## Create Azure AI Content Understanding Client\n",
     "\n",
-    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK.\n"
+    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK. Fill the constant **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, **AZURE_AI_API_KEY** with the information from your Azure AI Service.\n",
+    "\n",
+    "> ⚠️ Important:\n",
+    "You must update the code below to match your Azure authentication method.\n",
+    "Look for the `# IMPORTANT` comments and modify those sections accordingly.\n",
+    "If you skip this step, the sample may not run correctly."
    ]
   },
   {
@@ -118,7 +123,10 @@
     "load_dotenv(find_dotenv())\n",
     "logging.basicConfig(level=logging.INFO)\n",
     "\n",
+    "# For authentication, you can use either token-based auth or subscription key, and only one of them is required\n",
     "AZURE_AI_ENDPOINT = os.getenv(\"AZURE_AI_ENDPOINT\")\n",
+    "# IMPORTANT: Replace with your actual subscription key or set up in \".env\" file if not using token auth\n",
+    "AZURE_AI_API_KEY = os.getenv(\"AZURE_AI_API_KEY\")\n",
     "AZURE_AI_API_VERSION = os.getenv(\"AZURE_AI_API_VERSION\", \"2025-05-01-preview\")\n",
     "\n",
     "# Add the parent directory to the path to use shared modules\n",
@@ -132,7 +140,10 @@
     "client = AzureContentUnderstandingClient(\n",
     "    endpoint=AZURE_AI_ENDPOINT,\n",
     "    api_version=AZURE_AI_API_VERSION,\n",
+    "    # IMPORTANT: Comment out token_provider if using subscription key\n",
     "    token_provider=token_provider,\n",
+    "    # IMPORTANT: Uncomment this if using subscription key\n",
+    "    # subscription_key=AZURE_AI_API_KEY,\n",
     "    # x_ms_useragent=\"azure-ai-content-understanding-python/field_extraction\", # This header is used for sample usage telemetry, please comment out this line if you want to opt out.\n",
     ")"
    ]

notebooks/management.ipynb

@@ -38,7 +38,12 @@
    "source": [
     "## Create Azure AI Content Understanding Client\n",
     "\n",
-    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK.\n"
+    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK. Fill the constant **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, **AZURE_AI_API_KEY** with the information from your Azure AI Service.\n",
+    "\n",
+    "> ⚠️ Important:\n",
+    "You must update the code below to match your Azure authentication method.\n",
+    "Look for the `# IMPORTANT` comments and modify those sections accordingly.\n",
+    "If you skip this step, the sample may not run correctly."
    ]
   },
   {
@@ -58,7 +63,10 @@
     "load_dotenv(find_dotenv())\n",
     "logging.basicConfig(level=logging.INFO)\n",
     "\n",
+    "# For authentication, you can use either token-based auth or subscription key, and only one of them is required\n",
     "AZURE_AI_ENDPOINT = os.getenv(\"AZURE_AI_ENDPOINT\")\n",
+    "# IMPORTANT: Replace with your actual subscription key or set up in \".env\" file if not using token auth\n",
+    "AZURE_AI_API_KEY = os.getenv(\"AZURE_AI_API_KEY\")\n",
     "AZURE_AI_API_VERSION = os.getenv(\"AZURE_AI_API_VERSION\", \"2025-05-01-preview\")\n",
     "\n",
     "# Add the parent directory to the path to use shared modules \n",
@@ -72,7 +80,10 @@
     "client = AzureContentUnderstandingClient(\n",
     "    endpoint=AZURE_AI_ENDPOINT,\n",
     "    api_version=AZURE_AI_API_VERSION,\n",
+    "    # IMPORTANT: Comment out token_provider if using subscription key\n",
     "    token_provider=token_provider,\n",
+    "    # IMPORTANT: Uncomment this if using subscription key\n",
+    "    # subscription_key=AZURE_AI_API_KEY,\n",
     "    x_ms_useragent=\"azure-ai-content-understanding-python/analyzer_management\", # This header is used for sample usage telemetry, please comment out this line if you want to opt out.\n",
     ")"
    ]