オンライン エンドポイントのクライアントを認証する

  • [アーティクル]

適用対象:Azure CLI ml extension v2 (現行)Python SDK azure-ai-ml v2 (現行)

この記事では、オンライン エンドポイントでコントロール プレーンおよびデータ プレーンの操作を実行するためにクライアントを認証する方法について説明します。

"コントロール プレーン操作" により、エンドポイントの制御と変更を行います。 コントロール プレーン操作には、オンライン エンドポイントとオンライン デプロイの作成、読み取り、更新、削除 (CRUD) 操作が含まれます。

"データ プレーン操作" では、エンドポイントを変更せずに、データを使用してオンライン エンドポイントと対話します。 たとえば、データ プレーン操作を、オンライン エンドポイントへのスコアリング要求の送信と応答の取得で構成することができます。

前提条件

この記事の手順に従う前に、次の前提条件が満たされていることをご確認ください。

制限事項

Microsoft Entra トークン (aad_token) 認証モードを使用するエンドポイントでは、CLI az ml online-endpoint invoke、SDK ml_client.online_endpoints.invoke()、または Azure Machine Learning スタジオの[テスト] または [消費] タブを使用したスコア付けはサポートされていません。 代わりに、汎用 Python SDK を使用するか、または REST API を使用してコントロール プレーン トークンを渡します。 詳細については、「キーまたはトークンを使用してデータにスコアを付ける」を参照してください。

ユーザー ID を準備する

オンライン エンドポイントでコントロール プレーン操作 (つまり、CRUD 操作) およびデータ プレーン操作 (つまり、スコアリング要求の送信) を実行するには、ユーザー ID が必要です。 コントロール プレーン操作とデータ プレーン操作に同じユーザー ID を使用することも、異なるユーザー ID を使用することもできます。 この記事では、コントロール プレーン操作とデータ プレーン操作の両方に同じユーザー ID を使用します。

Microsoft Entra ID の下にユーザー ID を作成するには、「認証の設定」を参照してください。 ID は後で必要になります。

ID にアクセス許可を割り当てる

このセクションでは、エンドポイントとの対話に使用するユーザー ID にアクセス許可を割り当てます。 まず、組み込みロールを使用するか、カスタム役割を作成します。 その後、ロールをユーザー ID に割り当てます。

組み込みロールを使用する

AzureML Data Scientist 組み込みロールを使ってエンドポイントとデプロイの管理と利用ができます。これには、次の "コントロール プレーン" RBAC アクションがワイルドカードを使って含まれます。

  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/write
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/delete
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/read
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/action
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action

"データ プレーン" の次の RBAC アクションを含めます。

  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/score/action

必要に応じて、Azure Machine Learning Workspace Connection Secrets Reader 組み込みロールを使ってワークスペース接続からシークレットにアクセスできます。これには、次の "コントロール プレーン" RBAC アクションが含まれます。

  • Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action
  • Microsoft.MachineLearningServices/workspaces/metadata/secrets/read

これらの組み込みロールを使用する場合、この手順で必要なアクションはありません。

(省略可能) カスタム役割を作成する

組み込みロールまたは他の事前に作成されたカスタム役割を使用する場合は、この手順をスキップできます。

  1. ロールの JSON 定義を作成して、カスタム役割のスコープとアクションを定義します。 たとえば、次のロールの定義を使用すると、ユーザーは、指定したワークスペースでオンライン エンドポイントの CRUD を実行できます。

    custom-role-for-control-plane.json:

    {
    "Name": "Custom role for control plane operations - online endpoint",
    "IsCustom": true,
    "Description": "Can CRUD against online endpoints.",
    "Actions": [
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/write",
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/delete",
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/read",
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action",
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/action",
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action"
    ],
    "NotActions": [
    ],
    "AssignableScopes": [
        "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>"
    ]
}

    次のロールの定義を使用すると、ユーザーは、指定したワークスペースでオンライン エンドポイントにスコアリング要求を送信できます。

    custom-role-for-scoring.json:

    {
    "Name": "Custom role for scoring - online endpoint",
    "IsCustom": true,
    "Description": "Can score against online endpoints.",
    "Actions": [
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*/action"
    ],
    "NotActions": [
    ],
    "AssignableScopes": [
        "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>"
    ]
}

  2. JSON 定義を使用してカスタム役割を作成します。

    az role definition create --role-definition custom-role-for-control-plane.json --subscription <subscriptionId>

az role definition create --role-definition custom-role-for-scoring.json --subscription <subscriptionId>

    Note

    カスタム役割を作成するには、次の 3 つのロールのいずれかが必要です。

    • owner
    • ユーザー アクセス管理者
    • Microsoft.Authorization/roleDefinitions/write アクセス許可 (カスタム役割の作成、更新、削除) と、Microsoft.Authorization/roleDefinitions/read アクセス許可 (カスタム役割の表示) を持つカスタム役割。

    カスタム ロールの作成の詳細については、「Azure カスタム ロール」を参照してください。

  3. ロールの定義を確認します。

    az role definition list --custom-role-only -o table

az role definition list -n "Custom role for control plane operations - online endpoint"
az role definition list -n "Custom role for scoring - online endpoint"

export role_definition_id1=`(az role definition list -n "Custom role for control plane operations - online endpoint" --query "[0].id" | tr -d '"')`

export role_definition_id2=`(az role definition list -n "Custom role for scoring - online endpoint" --query "[0].id" | tr -d '"')`

ロールを ID に割り当てる

  1. AzureML Data Scientist 組み込みロールを使用している場合、次のコードを使用して、ロールをユーザー ID に割り当てます。

    az role assignment create --assignee <identityId> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

  2. 必要に応じて、Azure Machine Learning Workspace Connection Secrets Reader 組み込みロールを使っている場合、次のコードを使って、ロールをユーザー ID に割り当てます。

    az role assignment create --assignee <identityId> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

  3. カスタム役割を使用している場合は、次のコードを使用して、ロールをユーザー ID に割り当てます。

    az role assignment create --assignee <identityId> --role "Custom role for control plane operations - online endpoint" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

az role assignment create --assignee <identityId> --role "Custom role for scoring - online endpoint" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

    Note

    カスタム役割をユーザー ID に割り当てるには、次の 3 つのロールのいずれかが必要です。

    • owner
    • ユーザー アクセス管理者
    • Microsoft.Authorization/roleAssignments/write アクセス許可 (カスタム役割の割り当て) と、Microsoft.Authorization/roleAssignments/read (ロールの割り当ての表示) を許可するカスタム役割。

    さまざまな Azure ロールとそのアクセス許可の詳細については、「Azure ロール」およびAzure portal を使用した Azure ロールの割り当てに関するページを参照してください。

  4. ロールの割り当てを確認します。

    az role assignment list --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

コントロール プレーン操作用の Microsoft Entra トークンを取得する

トークンを直接使用する REST API を使用してコントロール プレーン操作を実行する予定の場合、この手順を行います。

Azure Machine Learning CLI (v2)、Python SDK (v2)、Azure Machine Learning スタジオなどの他の方法を使用する予定の場合、Microsoft Entra トークンを手動で取得する必要はありません。 サインイン時に、ユーザー ID は既に認証されており、トークンは自動的に取得されて渡されます。

"コントロール" プレーン操作用の Microsoft Entra トークンは、Azure リソース エンドポイント (https://management.azure.com) から取得できます。

  1. Azureにログインします。

    az login

  2. 特定の ID を使用する場合は、次のコードを使用して、その ID でサインインします。

    az login --identity --username <identityId>

  3. 次のコンテキストを使用してトークンを取得します。

    export CONTROL_PLANE_TOKEN=`(az account get-access-token --resource https://management.azure.com --query accessToken | tr -d '"')`

(省略可能) Microsoft Entra トークンのリソース エンドポイントとクライアント ID を確認する

Microsoft Entra トークンを取得した後、jwt.ms を介してトークンをデコードすると、次の情報を含む json 応答が返され、そのトークンが適切な Azure リソース エンドポイント management.azure.com および適切なクライアント ID 用であることを確認できます。

{
    "aud": "https://management.azure.com",
    "oid": "<your-object-id>"
}

エンドポイントの作成

次の例では、エンドポイント ID としてシステム割り当て ID (SAI) を使用してエンドポイントを作成します。 SAI は、エンドポイント用マネージド ID の既定の ID の種類です。 SAI には、一部の基本ロールが自動的に割り当てられます。 システム割り当て ID のロールの割り当ての詳細については、「エンドポイント ID のロールの自動割り当て」を参照してください。

CLI では、コントロール プレーン トークンを明示的に指定する必要はありません。 代わりに、CLI により、サインイン時にユーザーが認証され、トークンは自動的に取得されて渡されます。

  1. エンドポイント定義 YAML ファイルを作成します。

    endpoint.yml:

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: aad_token

  2. auth_mode は、キー認証の場合はkey に、Azure Machine Learning トークン認証の場合は aml_token に置き換えることができます。この例では、Microsoft Entra トークン認証に aad_token を使用しています。

    az ml online-endpoint create -f endpoint.yml

  3. エンドポイントの状態を確認します。

    az ml online-endpoint show -n my-endpoint

  4. エンドポイントの作成時に auth_mode を (たとえば、aad_token に) オーバーライドする場合は、次のコードを実行します。

    az ml online-endpoint create -n my-endpoint --auth_mode aad_token

  5. 既存のエンドポイントを作成更新し、auth_mode を (たとえば、aad_token に) 指定する場合、次のコードを実行します。

    az ml online-endpoint update -n my-endpoint --set auth_mode=aad_token

デプロイの作成

デプロイを作成するには、「オンライン エンドポイントを使用して ML モデルをデプロイする」または「REST を使用してオンライン エンドポイントとしてモデルをデプロイする」を参照してください。 さまざまな認証モードのデプロイの作成方法に違いはありません。

次のコードは、デプロイを作成する方法の例です。 オンライン エンドポイントのデプロイの詳細については、「オンライン エンドポイントを使用して ML モデルをデプロイする (CLI を使用)」を参照してください

  1. デプロイ定義 YAML ファイルを作成します。

    blue-deployment.yml:

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-aad-auth-endp1
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

  2. YAML ファイルを使用してデプロイを作成します。 この例では、すべてのトラフィックを新しいデプロイに設定します。

    az ml online-deployment create -f blue-deployment.yml --all-traffic

エンドポイントのスコアリング URI を取得する

CLI を使用してエンドポイントを呼び出す予定の場合、スコアリング URI は CLI によって自動的に処理されるため、明示的に取得する必要はありません。 ただし、REST API などの他のチャネルで使用できるようにするために、CLI を使用してスコアリング URI を取得することはできます。

scoringUri=$(az ml online-endpoint show -n my-endpoint --query "scoring_uri")

データ プレーン操作用のキーまたはトークンを取得する

キーまたはトークンを取得するプロセスがコントロール プレーン操作であっても、そのキーまたはトークンをデータ プレーン操作に使用できます。 つまり、コントロール プレーン トークンを使用してキーまたはトークンを取得し、それを、後でデータ プレーン操作を実行するために使用することができます。

"キー" または "Azure Machine Learning トークン" を取得するには、「コントロール プレーン操作の認証」 で説明されているように、それを要求しているユーザー ID に適切なロールが割り当てられている必要があります。 "Microsoft Entra トークン" を取得するために、ユーザー ID に追加のロールは必要ありません。

キーまたは Azure Machine Learning トークン

CLI を使用してエンドポイントを呼び出す予定で、エンドポイントが、キーまたは Azure Machine Learning トークン (aml_token) の認証モードを使用するように設定されている場合、データ プレーン トークンは CLI によって自動的に処理されるため、明示的に取得する必要はありません。 ただし、REST API などの他のチャネルで使用できるようにするために、CLI を使用してデータ プレーン トークンを取得することはできます。

キーまたは Azure Machine Learning トークン (aml_token) を取得するには、az ml online-endpoint get-credentials コマンドを使用します。 このコマンドから、キーまたは Azure Machine Learning トークンを含む JSON ドキュメントが返されます。

キーは、primaryKey および secondaryKey フィールドに返されます。 次の例では、--query パラメーターを使って主キーのみを返す方法を示します。

export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey)

Azure Machine Learning トークンは、accessToken フィールドに返されます。

export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)

また、expiryTimeUtc および refreshAfterTimeUtc フィールドには、トークンの有効期限と更新日時が含まれます。

Microsoft Entra トークン

CLI を使用して Microsoft Entra トークン (aad_token) を取得するには、az account get-access-token コマンドを使用します。 このコマンドからは、Microsoft Entra トークンを含む JSON ドキュメントが返されます。

Microsoft Entra トークン は accessToken フィールドに返されます。

export DATA_PLANE_TOKEN=`(az account get-access-token --resource https://ml.azure.com --query accessToken | tr -d '"')`

Note

  • CLI ml 拡張機能では、Microsoft Entra トークンの取得はサポートされていません。 代わりに、前のコードで説明したように、az account get-access-token を使用してください。
  • コントロール プレーン操作用のトークンとは異なり、データ プレーン操作用のトークンは、Azure リソース エンドポイント management.azure.com ではなく ml.azure.com から取得されます。

Microsoft Entra トークンのリソース エンドポイントとクライアント ID を確認する

Microsoft Entra トークンを取得した後、jwt.ms を介してトークンをデコードすると、次の情報を含む json 応答が返され、そのトークンが適切な Azure リソース エンドポイント ml.azure.com および適切なクライアント ID 用であることを確認できます。

{
    "aud": "https://ml.azure.com",
    "oid": "<your-object-id>"
}

キーまたはトークンを使用してデータにスコアを付ける

キーまたは Azure Machine Learning トークン

キーまたは Azure Machine Learning トークンを使用するエンドポイントの場合、az ml online-endpoint invoke を使用できます。 キーまたは Azure Machine Learning トークンは CLI によって自動的に処理されるため、明示的に渡す必要はありません。

az ml online-endpoint invoke -n my-endpoint -r request.json

Microsoft Entra トークン

Microsoft Entra トークンを使用するエンドポイントの場合、az ml online-endpoint invoke の使用はサポートされていません。 代わりに REST API を使用し、エンドポイントのスコアリング URI を使用してエンドポイントを呼び出します。

トラフィックのログと監視

エンドポイントの診断設定でトラフィックのログを有効にするには、「ログを有効または無効にする方法」の手順に従います。

診断設定が有効になっている場合、AmlOnlineEndpointTrafficLogs テーブルを調べて認証モードとユーザー ID を確認できます。

関連するコンテンツ