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)

  • Artykuł

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 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. 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 metody 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 mieć uprawnienia czytelnika na płaszczyźnie sterowania docelowego konta usługi 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": truewartość .

  • Nowoczesne podejście wymaga skonfigurowania odpowiednich ról tożsamości zarządzanej 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 języka Gremlin i bazy danych 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 usługą Azure Cosmos DB for NoSQL przy użyciu nowoczesnego podejścia.

Konfigurowanie 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 usługi 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ż ją skonfigurować, ale nie jest dostępna, daj jej 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ę do odczytu 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-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

Zdefiniuj 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

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 przypisań ról płaszczyzny sterowania i płaszczyzny danych na koncie usługi Azure Cosmos DB for NoSQL można skonfigurować połączenie, które działa w ramach tej 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 parametry 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, witryna Azure Portal i zestaw SDK platformy .NET obsługują przy użyciu tożsamości zarządzanej przypisanej przez system lub przypisanej przez 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 usługi Azure Cosmos DB, grupę zasobów i nazwę konta usługi Azure Cosmos DB.

Oto przykład użycia interfejsu API REST tworzenia źródła danych, który korzysta z nowoczesnegopodejś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

IdentityAuthType Jeśli właściwość nie jest częścią parametry połączenia, usługa Azure AI Search domyślnie jest zgodna ze starszym podejściem w celu zapewnienia zgodności z poprzednimi wersjami.

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 za pomocą 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]"},
    "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 języka Gremlin/MongoDB (wersja zapoznawcza)

W tej sekcji opisano kroki konfigurowania nawiązywania połączenia z usługą Azure Cosmos DB dla języka Gremlin/Mongo przy użyciu starszego podejścia.

Konfigurowanie 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 Języka Gremlin dodaj do parametry połączenia ciąg "ApiKind=Gremlin" i użyj interfejsu API REST w wersji zapoznawczej.
  • W przypadku obu rodzajów obsługiwane jest tylko starsze podejście — czyli IdentityAuthType=AccountKey całkowite pominięcie go jest jedynym prawidłowym parametry 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 indeksator zakończy się pomyślnie, 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łą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 języka Gremlin lub bazy danych MongoDB, jeśli ostatnio obracano klucze konta usługi Azure Cosmos DB, musisz poczekać do 15 minut, aż tożsamość zarządzana parametry połączenia będzie działać.

Zobacz też