Een indexeerfunctieverbinding met Azure Cosmos DB instellen via een beheerde identiteit

  • Artikel

In dit artikel wordt uitgelegd hoe u een indexeerfunctieverbinding met een Azure Cosmos DB-database instelt met behulp van een beheerde identiteit in plaats van referenties op te geven in de verbindingsreeks.'

U kunt een door het systeem toegewezen beheerde identiteit of een door de gebruiker toegewezen beheerde identiteit (preview) gebruiken. Beheerde identiteiten zijn Microsoft Entra-aanmeldingen en vereisen Azure-roltoewijzingen voor toegang tot gegevens in Azure Cosmos DB.

Vereisten

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

Roltoewijzing voor door het systeem toegewezen identiteit:

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

  • Voor Cosmos DB for NoSQL kunt u optioneel op rollen gebaseerde toegang afdwingen als de enige verificatiemethode voor gegevensverbindingen door deze in te true stellen disableLocalAuth voor uw Cosmos DB-account.

  • Voor Gremlin- en MongoDB-verzamelingen: ondersteuning voor indexeerfuncties is momenteel beschikbaar als preview-versie. Op dit moment bestaat er een preview-beperking waarvoor Azure AI Search verbinding moet maken met behulp van sleutels. U kunt nog steeds een beheerde identiteit en roltoewijzing instellen, maar Azure AI Search gebruikt alleen de roltoewijzing om sleutels voor de verbinding op te halen. Deze beperking betekent dat u geen op rollen gebaseerde benadering kunt configureren als uw indexeerfuncties verbinding maken met Gremlin of MongoDB met behulp van Search met beheerde identiteiten om verbinding te maken met Azure Cosmos DB.

  • U moet bekend zijn met de concepten en configuratie van de indexeerfunctie.

De gegevensbron maken

Maak de gegevensbron en geef een door het systeem toegewezen beheerde identiteit of een door de gebruiker toegewezen beheerde identiteit (preview) op in de verbindingsreeks.

Door het systeem toegewezen beheerde identiteit

De REST API, Azure Portal en de .NET SDK-ondersteuning met behulp van een door het systeem toegewezen beheerde identiteit.

Wanneer u verbinding maakt met een door het systeem toegewezen beheerde identiteit, is de enige wijziging in de definitie van de gegevensbron de indeling van de eigenschap Referenties. U geeft de databasenaam en een ResourceId op die geen accountsleutel of wachtwoord heeft. De ResourceId moet de abonnements-id van Azure Cosmos DB, de resourcegroep en de naam van het Azure Cosmos DB-account bevatten.

  • Voor SQL-verzamelingen is voor de verbindingsreeks geen ApiKind vereist.
  • Voor SQL-verzamelingen voegt u IdentityAuthType=AccessToken toe als op rollen gebaseerde toegang wordt afgedwongen als de enige verificatiemethode. Deze is niet van toepassing op MongoDB- en Gremlin-verzamelingen.
  • Voor MongoDB-verzamelingen voegt u ApiKind=MongoDb toe aan de verbindingsreeks en gebruikt u een preview-REST API.
  • Voor Gremlin-grafieken voegt u ApiKind=Gremlin toe aan de verbindingsreeks en gebruikt u een preview-REST API.

Hier volgt een voorbeeld van het maken van een gegevensbron voor het indexeren van gegevens uit een opslagaccount met behulp van de REST API voor gegevensbron maken en een beheerde identiteit verbindingsreeks. De indeling van de beheerde identiteit verbindingsreeks is hetzelfde voor de REST API, .NET SDK en 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

 
}

Door de gebruiker toegewezen beheerde identiteit (preview)

De REST API 2021-04-30-preview ondersteunt verbindingen op basis van een door de gebruiker toegewezen beheerde identiteit. Wanneer u verbinding maakt met een door de gebruiker toegewezen beheerde identiteit, zijn er twee wijzigingen in de definitie van de gegevensbron:

  • Eerst is de indeling van de eigenschap Referenties de naam van de database en een ResourceId die geen accountsleutel of wachtwoord heeft. De ResourceId moet de abonnements-id van Azure Cosmos DB, de resourcegroep en de naam van het Azure Cosmos DB-account bevatten.

    • Voor SQL-verzamelingen is voor de verbindingsreeks geen ApiKind vereist.
    • Voor SQL-verzamelingen voegt u IdentityAuthType=AccessToken toe als op rollen gebaseerde toegang wordt afgedwongen als de enige verificatiemethode. Deze is niet van toepassing op MongoDB- en Gremlin-verzamelingen.
    • Voor MongoDB-verzamelingen voegt u 'ApiKind=MongoDb' toe aan de verbindingsreeks
    • Voor Gremlin-grafieken voegt u 'ApiKind=Gremlin' toe aan de verbindingsreeks.

  • Ten tweede voegt u een 'identiteit'-eigenschap toe die de verzameling door de gebruiker toegewezen beheerde identiteiten bevat. Er moet slechts één door de gebruiker toegewezen beheerde identiteit worden opgegeven bij het maken van de gegevensbron. Stel deze in om 'userAssignedIdentities' te typen.

Hier volgt een voorbeeld van het maken van een indexeerfunctie voor een gegevensbronobject met behulp van de PREVIEW-api voor het maken of bijwerken van gegevensbron :

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
}

De index maken

De index geeft de velden in een document, kenmerken en andere constructies op die de zoekervaring vormgeven.

Hier volgt een REST API-aanroep voor index maken met een doorzoekbaar booktitle veld:

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

De indexeerfunctie maken

Een indexeerfunctie verbindt een gegevensbron met een doelzoekindex en biedt een schema voor het automatiseren van de gegevensvernieuwing. Zodra de index en gegevensbron zijn gemaakt, kunt u de indexeerfunctie maken en uitvoeren. Als de indexeerfunctie is geslaagd, zijn de verbindingssyntaxis en roltoewijzingen geldig.

Hier volgt een CREATE Indexer REST API-aanroep met een Azure Cosmos DB for NoSQL-indexeerfunctiedefinitie. De indexeerfunctie wordt uitgevoerd wanneer u de aanvraag indient.

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

Probleemoplossing

Als u onlangs uw Azure Cosmos DB-accountsleutels hebt gedraaid, moet u maximaal 15 minuten wachten totdat de beheerde identiteit werkt verbindingsreeks.

Controleer of het Azure Cosmos DB-account toegang heeft tot het selecteren van netwerken. U kunt firewallproblemen uitsluiten door de verbinding zonder beperkingen uit te voeren.

Zie ook