Konfigurera en indexerareanslutning till Azure Cosmos DB via en hanterad identitet

  • Artikel

Den här artikeln beskriver hur du konfigurerar en indexeraranslutning till en Azure Cosmos DB-databas med hjälp av en hanterad identitet i stället för att ange autentiseringsuppgifter i anslutningssträng."

Du kan använda en systemtilldelad hanterad identitet eller en användartilldelad hanterad identitet (förhandsversion). Hanterade identiteter är Microsoft Entra-inloggningar och kräver Azure-rolltilldelningar för åtkomst till data i Azure Cosmos DB.

Förutsättningar

$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)

Rolltilldelning för systemtilldelad identitet:

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

  • För Cosmos DB för NoSQL kan du använda rollbaserad åtkomst som den enda autentiseringsmetoden för dataanslutningar genom att ange disableLocalAuth till true för ditt Cosmos DB-konto.

  • För Gremlin- och MongoDB-samlingar: Indexer-stöd är för närvarande i förhandsversion. För närvarande finns det en förhandsgranskningsbegränsning som kräver att Azure AI Search ansluter med hjälp av nycklar. Du kan fortfarande konfigurera en hanterad identitet och rolltilldelning, men Azure AI Search använder bara rolltilldelningen för att hämta nycklar för anslutningen. Den här begränsningen innebär att du inte kan konfigurera en rollbaserad metod om indexerarna ansluter till Gremlin eller MongoDB med hjälp av Sök med hanterade identiteter för att ansluta till Azure Cosmos DB.

  • Du bör känna till indexerarens begrepp och konfiguration.

Skapa datakällan

Skapa datakällan och ange antingen en systemtilldelad hanterad identitet eller en användartilldelad hanterad identitet (förhandsversion) i anslutningssträng.

Systemtilldelad hanterad identitet

REST-API:et, Azure-portalen och .NET SDK-stödet med hjälp av en systemtilldelad hanterad identitet.

När du ansluter med en systemtilldelad hanterad identitet är den enda ändringen av datakällans definition formatet för egenskapen "autentiseringsuppgifter". Du anger databasnamnet och ett ResourceId som inte har någon kontonyckel eller lösenord. ResourceId måste innehålla prenumerations-ID för Azure Cosmos DB, resursgruppen och Azure Cosmos DB-kontonamnet.

  • För SQL-samlingar kräver anslutningssträng inte "ApiKind".
  • För SQL-samlingar lägger du till "IdentityAuthType=AccessToken" om rollbaserad åtkomst tillämpas som den enda autentiseringsmetoden. Det är inte tillämpligt för MongoDB- och Gremlin-samlingar.
  • För MongoDB-samlingar lägger du till "ApiKind=MongoDb" i anslutningssträng och använder ett REST API för förhandsversion.
  • För Gremlin-grafer lägger du till "ApiKind=Gremlin" i anslutningssträng och använder ett REST API för förhandsversion.

Här är ett exempel på hur du skapar en datakälla för att indexera data från ett lagringskonto med hjälp av REST-API:et Skapa datakälla och en hanterad identitet anslutningssträng. Det hanterade identitetsformatet anslutningssträng är detsamma för REST API, .NET SDK och Azure-portalen.

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

 
}

Användartilldelad hanterad identitet (förhandsversion)

REST API för förhandsversionen 2021-04-30 stöder anslutningar baserat på en användartilldelad hanterad identitet. När du ansluter med en användartilldelad hanterad identitet finns det två ändringar i datakällans definition:

  • Först är formatet för egenskapen "autentiseringsuppgifter" databasnamnet och ett ResourceId som inte har någon kontonyckel eller lösenord. ResourceId måste innehålla prenumerations-ID för Azure Cosmos DB, resursgruppen och Azure Cosmos DB-kontonamnet.

    • För SQL-samlingar kräver anslutningssträng inte "ApiKind".
    • För SQL-samlingar lägger du till "IdentityAuthType=AccessToken" om rollbaserad åtkomst tillämpas som den enda autentiseringsmetoden. Det är inte tillämpligt för MongoDB- och Gremlin-samlingar.
    • För MongoDB-samlingar lägger du till "ApiKind=MongoDb" i anslutningssträng
    • För Gremlin-grafer lägger du till "ApiKind=Gremlin" i anslutningssträng.

  • För det andra lägger du till en "identitetsegenskap" som innehåller samlingen med användartilldelade hanterade identiteter. Endast en användartilldelad hanterad identitet ska anges när datakällan skapas. Ange att den ska skriva "userAssignedIdentities".

Här är ett exempel på hur du skapar ett indexerardatakällans objekt med förhandsversionen av REST-API:et Skapa eller uppdatera datakälla :

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
}

Skapa indexet

Indexet anger fälten i ett dokument, attribut och andra konstruktioner som formar sökupplevelsen.

Här är ett REST API-anrop för skapa index med ett sökbart booktitle fält:

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 }
    ]
}

Skapa indexeraren

En indexerare ansluter en datakälla till ett målsökningsindex och tillhandahåller ett schema för att automatisera datauppdateringen. När indexet och datakällan har skapats är du redo att skapa och köra indexeraren. Om indexeraren lyckas är anslutningssyntaxen och rolltilldelningarna giltiga.

Här är ett Create Indexer REST API-anrop med en Azure Cosmos DB for NoSQL-indexeraredefinition. Indexeraren körs när du skickar begäran.

    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"
    }

Felsökning

Om du nyligen roterade dina Azure Cosmos DB-kontonycklar måste du vänta upp till 15 minuter på att den hanterade identiteten anslutningssträng ska fungera.

Kontrollera om Azure Cosmos DB-kontot har begränsad åtkomst till utvalda nätverk. Du kan utesluta eventuella brandväggsproblem genom att prova anslutningen utan begränsningar.

Se även