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.

Wymagania wstępne

Ograniczenia

Obsługa indeksatora dla usługi Azure Cosmos DB dla kolekcji Gremlin i MongoDB jest obecnie dostępna w wersji zapoznawczej. Obecnie ograniczenie wersji zapoznawczej 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 gremlin lub mongoDB.

Tworzenie przypisania roli w usłudze Azure Cosmos DB

  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 Konfigurowanie kontroli dostępu opartej na rolach przy użyciu identyfikatora Entra firmy Microsoft dla konta usługi Azure Cosmos DB.

Określanie tożsamości zarządzanej w parametry połączenia

Po przypisaniu roli możesz skonfigurować połączenie z usługą Azure Cosmos DB for NoSQL, która 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ą CosmosDB 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.

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

  • 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 usługi Cosmos DB 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=2024-07-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];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

Tożsamość zarządzana przypisana 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.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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];ApiKind=SQL;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
}

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

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ń.

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ż