マネージド ID を使用して Azure Cosmos DB へのインデクサー接続を設定する

  • [アーティクル]

この記事では、接続文字列で資格情報を指定する代わりに、マネージド ID を使用して Azure Cosmos DB データベースへのインデクサー接続を設定する方法を説明します。

システム割り当てマネージド ID またはユーザー割り当てマネージド ID (プレビュー) を使用できます。 マネージド ID は Microsoft Entra のログイン ID であり、Azure Cosmos DB のデータにアクセスするには Azure でのロールの割り当てが必要です。

前提条件

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription id>
$system_assigned_principal = <principal id for system assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

システム割り当て ID のロールの割り当て:

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

  • Cosmos DB for NoSQL の場合は任意で、Cosmos DB アカウントの disableLocalAuth を true に設定することで、データ接続の唯一の認証方法としてロールベースのアクセスを適用することができます。

  • Gremlin および MongoDB コレクションの場合: インデクサー サポートは現在、プレビュー段階です。 現時点では、Azure AI Search でキーを使用して接続することを要求するプレビュー制限があります。 それでもマネージド ID とロールの割り当てを設定できますが、Azure AI Search ではロールの割り当てのみを使用して接続のキーを取得します。 この制限は、お使いのインデクサーで Search を使用して Gremlin または MongoDB に接続している場合 (Azure Cosmos DB への接続にマネージド ID を使用)、ロールベースのアプローチを構成できないことを意味します。

  • インデクサーの概念と構成についてよく理解しておく必要があります。

データ ソースを作成する

データ ソースを作成し、接続文字列に、システム割り当てマネージド ID またはユーザー割り当てマネージド ID (プレビュー) のいずれかを指定します。

システム割り当てマネージド ID

REST API、Azure portal、および .NET SDK では、システム割り当てマネージド ID の使用がサポートされています。

システム割り当てマネージド ID を使用して接続する場合は、データソース定義に対して、"credentials" プロパティの形式を変更するだけで済みます。 データベース名と、アカウント キーまたはパスワードが設定されていない ResourceId を指定します。 ResourceId には、Azure Cosmos DB のサブスクリプション ID、リソースグループ、Azure Cosmos DB のアカウント名を含める必要があります。

  • SQL コレクションの場合は、接続文字列に "ApiKind" は必要ありません。
  • SQL コレクションについては、ロールベースのアクセスが唯一の認証方法として適用されている場合、"IdentityAuthType=AccessToken" を追加します。 MongoDB および Gremlin コレクションには適用されません。
  • MongoDB コレクションの場合は、"ApiKind=MongoDb" を接続文字列に追加し、プレビュー REST API を使用します。
  • Gremlin グラフの場合は、"ApiKind=Gremlin" を接続文字列に追加し、プレビュー REST API を使用します。

以下に、データ ソースの作成 REST API とマネージド ID 接続文字列を使用し、ストレージ アカウントのデータにインデックスを付けるためにデータ ソースを作成する方法の例を示します。 マネージド ID 接続文字列の形式は、REST API、.NET SDK、および Azure portal において同じです。

POST https://[service name].search.windows.net/datasources?api-version=2020-06-30
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=[SQL | Gremlin | MongoDB];IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

ユーザー割り当てマネージド ID (プレビュー)

2021-04-30-preview REST API では、ユーザー割り当てマネージド ID に基づく接続がサポートされています。 ユーザー割り当てマネージド ID を使用して接続する場合、データソースの定義に対する変更は次の 2 つとなります。

  • まず、"credentials" プロパティの形式は、データベース名とアカウント キーまたはパスワードを持たない ResourceId です。 ResourceId には、Azure Cosmos DB のサブスクリプション ID、リソースグループ、Azure Cosmos DB のアカウント名を含める必要があります。

    • SQL コレクションの場合は、接続文字列に "ApiKind" は必要ありません。
    • SQL コレクションについては、ロールベースのアクセスが唯一の認証方法として適用されている場合、"IdentityAuthType=AccessToken" を追加します。 MongoDB および Gremlin コレクションには適用されません。
    • MongoDB コレクションの場合は、"ApiKind=MongoDb" を接続文字列に追加します
    • Gremlin グラフの場合は、"ApiKind=Gremlin" を接続文字列に追加します。

  • 次に、ユーザー割り当てマネージド ID のコレクションを含む 「identity」 プロパティを追加します。 データ ソースを作成するとき、ユーザー割り当てマネージド ID を 1 つだけ指定する必要があります。 それを、"userAssignedIdentities" という型に設定します。

以下に、プレビュー段階にあるデータ ソースの作成または更新 REST API を使用してインデクサー データ ソース オブジェクトを作成する方法の例を示します。

POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=[SQL | Gremlin | MongoDB];IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { 
        "name": "[my-cosmos-collection]", "query": null 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    },
    "dataChangeDetectionPolicy": null
}

インデックスの作成

インデックスでは、検索に使用する、ドキュメント内のフィールド、属性、およびその他の構成要素を指定します。

次に、検索可能な booktitle フィールドを使用して [インデックスの作成] REST API を呼び出す方法を示します。

POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-target-index",
    "fields": [
    { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "booktitle", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
    ]
}

インデクサーを作成する

インデクサーはデータ ソースをターゲットの検索インデックスに接続し、データ更新を自動化するスケジュールを提供します。 インデックスとデータ ソースを作成したら、インデクサーを作成して実行する準備は完了です。 インデクサーが成功した場合、接続構文とロールの割り当ては有効です。

以下に、Azure Cosmos DB for NoSQL インデクサー定義を使用してインデクサーの作成 REST API を呼び出す方法を示します。 要求を送信すると、インデクサーが実行されます。

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
    Content-Type: application/json
    api-key: [admin key]

    {
      "name" : "cosmos-db-indexer",
      "dataSourceName" : "cosmos-db-datasource",
      "targetIndexName" : "my-target-index"
    }

トラブルシューティング

Azure Cosmos DB アカウント キーを最近ローテーションした場合は、マネージド ID 接続文字列が機能するまでに最大で 15 分間待つ必要があります。

Azure Cosmos DB アカウントで、特定のネットワークへのアクセスが制限されているかどうかを確認します。 制限を設定せずに接続を試すことにより、ファイアウォールの問題を除外できます。

関連項目