Konfigurowanie połączenia indeksatora z usługą Azure Cosmos DB za pośrednictwem tożsamości zarządzanej

Artykuł
04/19/2024

W tym artykule wyjaśniono, jak skonfigurować połączenie indeksatora z bazą danych usługi Azure Cosmos DB przy użyciu tożsamości zarządzanej zamiast podawania poświadczeń w parametry połączenia.

Można użyć tożsamości zarządzanej przypisanej przez system lub tożsamości zarządzanej przypisanej przez użytkownika (wersja zapoznawcza). Tożsamości zarządzane to identyfikatory logowania firmy Microsoft Entra i wymagają przypisań ról platformy Azure w celu uzyskania dostępu do danych w usłudze Azure Cosmos DB.

Wymagania wstępne

Utwórz tożsamość zarządzaną dla usługi wyszukiwania.
Przypisz rolę Czytelnik konta usługi Cosmos DB do tożsamości zarządzanej usługi wyszukiwania. Ta rola umożliwia odczytywanie danych konta usługi Azure Cosmos DB. Aby uzyskać więcej informacji na temat przypisań ról w usłudze Cosmos DB, zobacz Konfigurowanie kontroli dostępu opartej na rolach do danych.
Przypisanie roli płaszczyzny danych: postępuj zgodnie z przypisaniem roli płaszczyzny danych, aby dowiedzieć się więcej.
Przykład przypisania roli płaszczyzny danych tylko do odczytu:

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

Przypisanie roli dla tożsamości przypisanej przez system:

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

W przypadku usługi Cosmos DB for NoSQL można opcjonalnie wymusić dostęp oparty na rolach jako jedyną metodę uwierzytelniania dla połączeń danych, ustawiając wartość disableLocalAuth na true wartość dla konta usługi Cosmos DB.
W przypadku kolekcji Gremlin i MongoDB: obsługa indeksatora jest obecnie dostępna w wersji zapoznawczej. Obecnie istnieje ograniczenie wersji zapoznawczej, które wymaga, aby usługa Azure AI Search łączyła się przy użyciu kluczy. Nadal można skonfigurować tożsamość zarządzaną i przypisanie roli, ale usługa Azure AI Search będzie używać tylko przypisania roli do pobierania kluczy dla połączenia. To ograniczenie oznacza, że nie można skonfigurować podejścia opartego na rolach, jeśli indeksatory łączą się z językiem Gremlin lub MongoDB przy użyciu funkcji wyszukiwania z tożsamościami zarządzanymi w celu nawiązania połączenia z usługą Azure Cosmos DB.
Należy zapoznać się z pojęciami i konfiguracją indeksatora.

Utwórz źródło danych

Utwórz źródło danych i podaj tożsamość zarządzaną przypisaną przez system lub tożsamość zarządzaną przypisaną przez użytkownika (wersja zapoznawcza) w parametry połączenia.

Tożsamość zarządzana przypisana przez system

Interfejs API REST, witryna Azure Portal i zestaw SDK platformy .NET obsługują tożsamość zarządzaną przypisaną przez system.

Podczas nawiązywania połączenia z tożsamością zarządzaną przypisaną przez system jedyną zmianą definicji źródła danych jest format właściwości "credentials". Podasz nazwę bazy danych i identyfikator ResourceId, który nie ma klucza konta ani hasła. Identyfikator zasobu musi zawierać identyfikator subskrypcji usługi Azure Cosmos DB, grupę zasobów i nazwę konta usługi Azure Cosmos DB.

W przypadku kolekcji SQL parametry połączenia nie wymaga "ApiKind".
W przypadku kolekcji SQL dodaj wartość "IdentityAuthType=AccessToken", jeśli dostęp oparty na rolach jest wymuszany jako jedyna metoda uwierzytelniania. Nie ma zastosowania do kolekcji MongoDB i Gremlin.
W przypadku kolekcji bazy danych MongoDB dodaj do parametry połączenia element "ApiKind=MongoDb" i użyj interfejsu API REST w wersji zapoznawczej.
W przypadku grafów Języka Gremlin dodaj do parametry połączenia ciąg "ApiKind=Gremlin" i użyj interfejsu API REST w wersji zapoznawczej.

Oto przykład tworzenia źródła danych w celu indeksowania danych z konta magazynu przy użyciu interfejsu API REST tworzenia źródła danych i tożsamości zarządzanej parametry połączenia. Format tożsamości zarządzanej parametry połączenia jest taki sam dla interfejsu API REST, zestawu .NET SDK i witryny 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

 
}

Tożsamość zarządzana przypisana przez użytkownika (wersja zapoznawcza)

Interfejs API REST 2021-04-30-preview obsługuje połączenia oparte na tożsamości zarządzanej przypisanej przez użytkownika. Podczas nawiązywania połączenia z tożsamością zarządzaną przypisaną przez użytkownika istnieją dwie zmiany definicji źródła danych:

Najpierw format właściwości "credentials" to nazwa bazy danych i identyfikator ResourceId, który nie ma klucza konta ani hasła. Identyfikator zasobu musi zawierać identyfikator subskrypcji usługi Azure Cosmos DB, grupę zasobów i nazwę konta usługi Azure Cosmos DB.
- W przypadku kolekcji SQL parametry połączenia nie wymaga "ApiKind".
- W przypadku kolekcji SQL dodaj wartość "IdentityAuthType=AccessToken", jeśli dostęp oparty na rolach jest wymuszany jako jedyna metoda uwierzytelniania. Nie ma zastosowania do kolekcji MongoDB i Gremlin.
- W przypadku kolekcji bazy danych MongoDB dodaj do parametry połączenia element "ApiKind=MongoDb"
- W przypadku grafów Języka Gremlin dodaj do parametry połączenia ciąg "ApiKind=Gremlin".
Po drugie należy dodać właściwość "identity", która zawiera kolekcję tożsamości zarządzanych przypisanych przez użytkownika. Podczas tworzenia źródła danych należy podać tylko jedną tożsamość zarządzaną przypisaną przez użytkownika. Ustaw go na wartość "userAssignedIdentities".

Oto przykład tworzenia obiektu źródła danych indeksatora przy użyciu interfejsu API REST tworzenia lub aktualizowania źródła danych w wersji zapoznawczej:

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
}

Tworzenie indeksu

Indeks określa pola w dokumencie, atrybutach i innych konstrukcjach, które kształtuje środowisko wyszukiwania.

Oto wywołanie interfejsu API REST tworzenia indeksu z polem z możliwością booktitle wyszukiwania:

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

Tworzenie indeksatora

Indeksator łączy źródło danych z docelowym indeksem wyszukiwania i udostępnia harmonogram automatyzowania odświeżania danych. Po utworzeniu indeksu i źródła danych możesz utworzyć i uruchomić indeksator. Jeśli indeksator zakończy się pomyślnie, składnia połączenia i przypisania ról są prawidłowe.

Oto wywołanie interfejsu API REST create indexer z definicją indeksatora NoSQL w usłudze Azure Cosmos DB. Indeksator jest uruchamiany podczas przesyłania żądania.

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

Rozwiązywanie problemów

Jeśli ostatnio obracano klucze konta usługi Azure Cosmos DB, musisz poczekać do 15 minut, zanim tożsamość zarządzana parametry połączenia będzie działać.

Sprawdź, czy konto usługi Azure Cosmos DB ma dostęp ograniczony do wybierania sieci. Wszelkie problemy z zaporą można wykluczyć, próbując nawiązać połączenie bez ograniczeń.