Azure Cognitive Services Management Client

Warnings

• breaking Authentication mechanisms have significantly evolved in Azure SDK for Python. Older libraries used `ServicePrincipalCredentials` or similar direct credential objects. Modern SDKs (like `azure-mgmt-cognitiveservices` v14.x) primarily use `azure-identity` with `DefaultAzureCredential` for a unified and more secure authentication experience.
  Fix: Migrate authentication to `azure-identity.DefaultAzureCredential`. Ensure environment variables like `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET` (for service principal) or `AZURE_SUBSCRIPTION_ID` are set.
• gotcha This library (`azure-mgmt-cognitiveservices`) is a 'control plane' client, used for managing (creating, deleting, configuring) Cognitive Services *accounts*. It is NOT for interacting with the Cognitive Services APIs themselves (e.g., performing text analysis, speech-to-text, or computer vision tasks).
  Fix: For data plane operations (calling the actual AI services), use specific 'data plane' SDKs like `azure-ai-textanalytics`, `azure-cognitiveservices-speech`, or `azure-ai-vision`.
• gotcha Many resource creation/deletion operations in Azure management clients are long-running operations (LROs). Methods like `begin_create()` or `begin_delete()` return a poller object, not the final resource.
  Fix: Always call `.result()` on the poller object returned by `begin_*` methods (e.g., `client.accounts.begin_create(...).result()`) to wait for the operation to complete and retrieve the final resource or confirmation of completion.
• gotcha Cognitive Services account names must be globally unique across Azure, not just within your subscription or resource group, for some service kinds.
  Fix: When creating an account, ensure the `account_name` parameter is unique. A common practice is to append a random string or timestamp to a base name.

Install

• pip install azure-mgmt-cognitiveservices azure-identity Install core and authentication packages

Imports

• CognitiveServicesManagementClient

  from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient

• DefaultAzureCredential

  from azure.identity import DefaultAzureCredential

  Required for authenticating to Azure using standard credential flows. Install `azure-identity` separately.

Quickstart

This quickstart demonstrates how to authenticate with `DefaultAzureCredential`, create a `CognitiveServicesManagementClient`, list existing Cognitive Services accounts within a resource group, and create a new Cognitive Services account. It uses environment variables for Azure subscription, resource group, and location.

import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient

# Ensure these environment variables are set:
# AZURE_SUBSCRIPTION_ID
# AZURE_RESOURCE_GROUP_NAME (e.g., 'myResourceGroup')
# AZURE_LOCATION (e.g., 'eastus')

subscription_id = os.environ.get("AZURE_SUBSCRIPTION_ID", "")
resource_group_name = os.environ.get("AZURE_RESOURCE_GROUP_NAME", "")
location = os.environ.get("AZURE_LOCATION", "eastus")
account_name = "myunique_cogsrv_account" # Must be globally unique for some services

if not all([subscription_id, resource_group_name]):
    raise ValueError("Please set AZURE_SUBSCRIPTION_ID and AZURE_RESOURCE_GROUP_NAME environment variables.")

# Authenticate with Azure
credential = DefaultAzureCredential()

# Create Cognitive Services Management Client
client = CognitiveServicesManagementClient(credential, subscription_id)

print(f"Listing Cognitive Services accounts in resource group '{resource_group_name}':")
for account in client.accounts.list_by_resource_group(resource_group_name):
    print(f"- {account.name} (Kind: {account.kind}, Location: {account.location})")

# Example: Create a new account (if it doesn't exist)
print(f"\nAttempting to create/update account '{account_name}'...")
account_properties = {
    "sku": {"name": "F0"}, # F0 is the free tier
    "kind": "TextAnalytics", # Example kind: 'TextAnalytics', 'Face', 'SpeechServices'
    "location": location,
    "properties": {}
}

try:
    # begin_create returns a poller for long-running operations
    poller = client.accounts.begin_create(
        resource_group_name,
        account_name,
        account_properties
    )
    new_account = poller.result() # Wait for the operation to complete
    print(f"Successfully created/updated account: {new_account.name} (ID: {new_account.id})")
except Exception as e:
    print(f"Error creating/updating account: {e}")