Nawiązywanie połączenia z Azure Cosmos DB przy użyciu tożsamości zarządzanej (Wyszukiwanie AI platformy Azure)

W tym artykule wyjaśniono, jak skonfigurować połączenie indeksatora z bazą danych 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. Tożsamości zarządzane w systemie Microsoft Entra wymagają przypisań ról Azure, aby uzyskać dostęp do danych w Azure Cosmos DB. Opcjonalnie możesz wymusić dostęp oparty na rolach jako jedyną metodę uwierzytelniania dla połączeń danych, ustawiając disableLocalAuth na true dla konta NoSQL Azure Cosmos DB.

Wymagania wstępne

• Utwórz tożsamość zarządzaną dla usługi wyszukiwania.

Ograniczenia

• Indeksatory łączące się z Azure Cosmos DB dla języka Gremlin i bazy danych MongoDB (obecnie w wersji zapoznawczej) obsługują tylko podejście legacy.

Obsługiwane podejścia w zakresie uwierzytelniania tożsamości zarządzanej

Wyszukiwanie AI platformy Azure obsługuje dwa mechanizmy łączenia się z Azure Cosmos DB przy użyciu tożsamości zarządzanej.

• Podejście legacy wymaga skonfigurowania zarządzanej tożsamości w celu uzyskania uprawnień czytelnika na warstwie sterowania docelowego konta Azure Cosmos DB. Wyszukiwanie AI platformy Azure używa tej tożsamości do pobierania kluczy konta usługi Cosmos DB w tle w celu uzyskania dostępu do danych. Takie podejście nie zadziała, jeśli konto usługi Cosmos DB ma "disableLocalAuth": true.

• Podejście nowoczesne wymaga skonfigurowania odpowiednich ról tożsamości zarządzanej na warstwie kontrolnej i danych docelowego konta Azure Cosmos DB. Wyszukiwanie AI platformy Azure następnie zażąda tokenu dostępu w celu uzyskania dostępu do danych na koncie usługi Cosmos DB. Takie podejście działa nawet wtedy, gdy konto usługi Cosmos DB ma wartość "disableLocalAuth": true.

Indeksatory łączące się z Azure Cosmos DB dla NoSQL obsługują zarówno podejście legacy, jak i modern – zaleca się podejście modern.

Nawiązywanie połączenia z Azure Cosmos DB na potrzeby NoSQL

W tej sekcji opisano kroki konfigurowania nawiązywania połączenia z Azure Cosmos DB dla NoSQL za pośrednictwem modern podejścia.

Konfiguracja przypisań ról płaszczyzny sterowania

1. Zaloguj się do portalu Azure i znajdź usługę Cosmos DB dla konta NoSQL.

2. Wybierz pozycję Kontrola dostępu (IAM).

3. Wybierz pozycję Dodaj , a następnie wybierz pozycję Przypisanie roli.

4. Z listy ról funkcji pracy wybierz Cosmos DB Account Reader.

5. Wybierz pozycję Dalej.

6. Wybierz pozycję Tożsamość zarządzana , a następnie wybierz pozycję Członkowie.

7. Filtruj według tożsamości zarządzanych przypisanych przez system lub tożsamości zarządzanych przypisanych przez użytkownika. Powinna zostać wyświetlona tożsamość zarządzana, która została wcześniej utworzona dla usługi wyszukiwania. Jeśli go nie masz, zobacz Konfigurowanie wyszukiwania w celu korzystania z tożsamości zarządzanej. Jeśli już ją skonfigurowałeś/skonfigurowałaś, ale nie jest dostępna, daj jej kilka minut.

8. Wybierz tożsamość i zapisz przypisanie roli.

Aby uzyskać więcej informacji, zobacz Użyj kontroli dostępu opartej na rolach płaszczyzny sterowania za pomocą Azure Cosmos DB dla NoSQL.

Konfigurowanie przypisań ról płaszczyzny danych

Tożsamość zarządzana musi otrzymać przydzieloną rolę do odczytu z warstwy danych konta Cosmos DB. Identyfikator obiektu (podmiotu) dla tożsamości przypisanej przez system/użytkownika usługi wyszukiwania można znaleźć na karcie "Tożsamość" usługi wyszukiwania. Ten krok można wykonać tylko za pośrednictwem Azure CLI w tej chwili.

Ustaw zmienne:

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$scope=$(az cosmosdb show --name $cosmosdb_acc_name --resource-group $resource_group --query id --output tsv)

Zdefiniuj przypisanie roli dla tożsamości przypisanej przez system:

az cosmosdb sql role assignment create --account-name $cosmosdb_acc_name --resource-group $resource_group --role-definition-id $readOnlyRoleDefinitionId --principal-id $system_assigned_principal --scope $scope

Aby uzyskać więcej informacji, zobacz Użyj kontroli dostępu opartej na rolach w płaszczyźnie danych z Azure Cosmos DB dla NoSQL

Konfigurowanie definicji źródła danych

Po skonfigurowaniu przypisań ról zarówno płaszczyzny sterowania, jak i płaszczyzny danych na koncie Azure Cosmos DB dla NoSQL, można skonfigurować połączenie, które będzie działać zgodnie z tą rolą.

Indeksatory używają obiektu źródła danych do połączeń z zewnętrznym źródłem danych. W tej sekcji wyjaśniono, jak określić zarządzaną tożsamość przypisaną przez system lub zarządzaną tożsamość przypisaną przez użytkownika w ciągu połączenia źródła danych. Więcej przykładów ciągów połączenia można znaleźć w artykule dotyczącym tożsamości zarządzanych.

Interfejs REST, portal Azure oraz .NET SDK obsługują korzystanie z tożsamości zarządzanej przypisanej do systemu lub użytkownika.

Nawiązywanie połączenia za pośrednictwem tożsamości przypisanej 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". Podaj nazwę bazy danych i identyfikator ResourceId, który nie ma klucza konta ani hasła. Identyfikator zasobu musi zawierać identyfikator subskrypcji Azure Cosmos DB, grupę zasobów i nazwę konta Azure Cosmos DB.

Oto przykład użycia interfejsu API REST tworzenia źródła danych , który korzysta z nowoczesnego podejścia.

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
{
    "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];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Nawiązywanie połączenia za pośrednictwem tożsamości przypisanej przez użytkownika

Musisz dodać właściwość "identity" do definicji źródła danych, w której określisz określoną tożsamość (z kilku, które można przypisać do usługi wyszukiwania), która będzie używana do łączenia się z kontem Azure Cosmos DB.

Oto przykład użycia tożsamości przypisanej przez użytkownika za pomocą nowoczesnego podejścia.

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
{
    "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];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Nawiązywanie połączenia z Azure Cosmos DB dla Gremlin/MongoDB (wersja zapoznawcza)

W tej sekcji opisano kroki konfigurowania nawiązywania połączenia z Azure Cosmos DB dla języka Gremlin/Mongo za pośrednictwem podejścia legacy.

Konfiguracja przypisań ról płaszczyzny sterowania

Wykonaj te same kroki co poprzednio, aby przypisać odpowiednie role na płaszczyźnie sterowania Azure Cosmos DB dla języka Gremlin/MongoDB.

Ustaw łańcuch połączenia

• W przypadku kolekcji bazy danych MongoDB dodaj do ciągu połączenia element "ApiKind=MongoDb" i użyj wersji zapoznawczej interfejsu API REST.
• W przypadku grafów Gremlina dodaj "ApiKind=Gremlin" do ciągu połączenia i użyj interfejsu API REST w wersji zapoznawczej.
• W przypadku obu rodzajów obsługiwane jest tylko podejście "legacy" — to znaczy użycie lub całkowite pominięcie go jest jedynym prawidłowym ciągiem połączenia.

Oto przykład łączenia się z kolekcjami bazy danych MongoDB przy użyciu tożsamości przypisanej przez system za pośrednictwem interfejsu API REST

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
{
    "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=MongoDb"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null
}

Oto przykład łączenia się z grafami języka Gremlin przy użyciu tożsamości przypisanej przez użytkownika.

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
{
    "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=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Uruchom indeksator, aby zweryfikować uprawnienia

Informacje o połączeniu i uprawnienia w usłudze zdalnej są weryfikowane w czasie wykonywania indeksatora. Jeśli indeksacja zakończy się sukcesem, składnia połączenia i przypisania ról są prawidłowe. Aby uzyskać więcej informacji, zobacz Uruchamianie lub resetowanie indeksatorów, umiejętności lub dokumentów.

Rozwiązywanie problemów z połączeniami

• W przypadku Azure Cosmos DB dla NoSQL sprawdź, czy konto ma dostęp ograniczony do wybierania sieci. Wszelkie problemy z zaporą można wykluczyć, próbując nawiązać połączenie bez ograniczeń. Aby uzyskać więcej informacji, zobacz Indexer access to content protected by Azure network security (Dostęp do zawartości chronionej przez zabezpieczenia sieci Azure

• W przypadku Azure Cosmos DB dla NoSQL, jeśli indeksacja nie powiedzie się z powodu problemów z uwierzytelnianiem, upewnij się, że przypisania ról zostały wykonane zarówno na płaszczyźnie kontrolnej, jak i na płaszczyźnie danych konta usługi Cosmos DB.

• W przypadku usługi Gremlin lub bazy danych MongoDB, jeśli ostatnio zmieniono klucze konta Azure Cosmos DB, musisz poczekać do 15 minut, aż będzie działać tożsamość zarządzana oraz ciąg połączenia.

Zobacz też

• Indeksowanie w Azure Cosmos DB dla NoSQL
• Indeksowanie za pośrednictwem Azure Cosmos DB dla bazy danych MongoDB (wersja zapoznawcza)
• Indeksowanie za pośrednictwem Azure Cosmos DB dla języka Apache Gremlin (wersja zapoznawcza)