Udostępnij za pośrednictwem

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

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. Tożsamości zarządzane to loginy Microsoft Entra i wymagają przypisania ról Azure w celu uzyskania dostępu do danych w usłudze Azure Cosmos DB. Opcjonalnie możesz 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 Azure Cosmos DB for NoSQL.

Wymagania wstępne

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

Usługa Azure AI Search obsługuje dwa mechanizmy łączenia się z usługą Azure Cosmos DB przy użyciu tożsamości zarządzanej.

  • Starsze podejście wymaga skonfigurowania tożsamości zarządzanej, aby uzyskać uprawnienia do odczytu na płaszczyźnie kontrolnej docelowego konta Azure Cosmos DB. Usługa Azure AI Search korzysta z tej tożsamości, aby pobrać klucze konta usługi Cosmos DB w tle w celu uzyskania dostępu do danych. Takie podejście nie będzie działać, jeśli konto usługi Cosmos DB ma "disableLocalAuth": true.

  • Nowoczesne podejście wymaga skonfigurowania odpowiednich ról związanych z tożsamością zarządzaną na płaszczyźnie sterowania i danych docelowego konta usługi Azure Cosmos DB. Usługa Azure AI Search zażąda następnie 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 usługą Azure Cosmos DB for NoSQL obsługują zarówno starsze, jak i nowoczesne podejście — nowoczesne podejście jest zdecydowanie zalecane.

Ograniczenia

  • Indeksatory łączące się z usługą Azure Cosmos DB dla Gremlin i MongoDB (obecnie w wersji zapoznawczej) obsługują tylko starsze podejście.

Nawiązywanie połączenia z usługą Azure Cosmos DB for NoSQL

W tej sekcji opisano kroki konfigurowania nawiązywania połączenia z Azure Cosmos DB for NoSQL przy użyciu nowoczesnego podejścia.

Konfiguracja przypisań ról płaszczyzny sterowania

  1. Zaloguj się do witryny Azure Portal i znajdź konto usługi Cosmos DB for 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 zadania wybierz pozycję Czytelnik konta Cosmos DB.

  5. Wybierz 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ż to skonfigurowałeś, ale nie jest dostępne, poczekaj kilka minut.

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

Aby uzyskać więcej informacji, zobacz Use control plane-based access control with Azure Cosmos DB for NoSQL (Używanie kontroli dostępu opartej na rolach płaszczyzny sterowania za pomocą usługi Azure Cosmos DB for NoSQL).

Konfigurowanie przypisań ról płaszczyzny danych

Tożsamość zarządzana musi mieć przypisaną rolę, aby móc odczytywać z płaszczyzny danych konta usługi 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 interfejsu wiersza polecenia platformy Azure 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 Use data plane-based access control with Azure Cosmos DB for NoSQL (Używanie kontroli dostępu opartej na rolach płaszczyzny danych za pomocą usługi Azure Cosmos DB dla NoSQL)

Konfigurowanie definicji źródła danych

Po skonfigurowaniu zarówno przypisań ról płaszczyzny sterowania, jak i płaszczyzny danych na koncie usługi Azure Cosmos DB for NoSQL, można skonfigurować połączenie z tą usługą, które działa w ramach przydzielonej roli.

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ć tożsamość zarządzaną przypisaną przez system lub tożsamość zarządzaną przypisaną przez użytkownika w parametry połączenia źródła danych. Więcej przykładów łańcuchów połączenia można znaleźć w artykule dotyczącym tożsamości zarządzanej.

Napiwek

Możesz utworzyć połączenie źródła danych z usługą Cosmos DB w witrynie Azure Portal, określając tożsamość zarządzaną przypisaną przez użytkownika lub systemową, a następnie wyświetlić definicję JSON, aby zobaczyć, jak sformułowano parametry połączenia.

Interfejs API REST, portal Azure oraz zestaw SDK platformy .NET obsługują korzystanie z tożsamości zarządzanej przypisanej przez system 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 zawiera 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.

Oto przykład użycia interfejsu Create Data Source API REST, który korzysta z nowoczesnego podejścia.

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

Uwaga

Jeśli właściwość IdentityAuthType nie jest częścią parametru połączenia, usługa Azure AI Search domyślnie stosuje starsze podejście, aby zapewnić zgodność wsteczną.

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 usługi Azure Cosmos DB.

Oto przykład użycia tożsamości przypisanej przez użytkownika w nowoczesny sposób.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-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];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 usługą Azure Cosmos DB dla Gremlin/MongoDB (wersja próbna)

W tej sekcji opisano kroki konfigurowania połączenia z usługą Azure Cosmos DB dla interfejsu Gremlin/Mongo przy użyciu 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 usługi Azure Cosmos DB dla języka Gremlin/MongoDB.

Ustawianie parametrów połączenia

  • 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 Gremlin dodaj do ciągu połączenia "ApiKind=Gremlin" i użyj wersji zapoznawczej REST API.
  • Dla obu rodzajów obsługiwane jest tylko starsze podejście - czyli IdentityAuthType=AccountKey lub całkowite pominięcie go jest jedynym prawidłowym parametrem 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=2024-11-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=2024-11-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 działanie indeksatora zakończy się powodzeniem, składnia dla 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łączeniem

  • W przypadku usługi Azure Cosmos DB for 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 Indeksator dostępu do zawartości chronionej przez zabezpieczenia sieci platformy Azure

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

  • W przypadku Gremlin lub MongoDB, jeśli ostatnio zmieniałeś klucze konta usługi Azure Cosmos DB, musisz poczekać do 15 minut, aż parametry połączenia tożsamości zarządzanej będą działać.

Zobacz też