Configurare una connessione dell'indicizzatore ad Azure Cosmos DB tramite un'identità gestita

  • Articolo

Questo articolo illustra come configurare una connessione dell'indicizzatore a un database di Azure Cosmos DB usando un'identità gestita anziché fornire le credenziali nel stringa di connessione".

È possibile usare un'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente (anteprima). Le identità gestite sono account di accesso di Microsoft Entra e richiedono assegnazioni di ruolo di Azure per accedere ai dati in Azure Cosmos DB.

Prerequisiti

  • Creare un'identità gestita per il servizio di ricerca.

  • Assegnare il ruolo Lettore account Cosmos DB all'identità gestita del servizio di ricerca. Questo ruolo concede la possibilità di leggere i dati dell'account Azure Cosmos DB. Per altre informazioni sulle assegnazioni di ruolo in Cosmos DB, vedere Configurare il controllo degli accessi in base al ruolo ai dati.

  • Assegnazione di ruolo piano dati: seguire l'assegnazione del ruolo del piano dati per altre informazioni.

  • Esempio per un'assegnazione di ruolo del piano dati di sola lettura:

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

Assegnazione di ruolo per l'identità assegnata dal sistema:

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

  • Per Cosmos DB per NoSQL, facoltativamente , è possibile applicare l'accesso basato sui ruoli come unico metodo di autenticazione per le connessioni dati impostando su disableLocalAuthtrue per l'account Cosmos DB.

  • Per le raccolte Gremlin e MongoDB: il supporto dell'indicizzatore è attualmente in anteprima. Attualmente esiste una limitazione di anteprima che richiede la connessione di Ricerca intelligenza artificiale di Azure tramite chiavi. È comunque possibile configurare un'identità gestita e un'assegnazione di ruolo, ma Ricerca di intelligenza artificiale di Azure userà solo l'assegnazione di ruolo per ottenere le chiavi per la connessione. Questa limitazione significa che non è possibile configurare un approccio basato sui ruoli se gli indicizzatori si connettono a Gremlin o MongoDB usando La ricerca con identità gestite per connettersi ad Azure Cosmos DB.

  • È necessario avere familiarità con i concetti e la configurazione dell'indicizzatore.

Creare l'origine dati

Creare l'origine dati e fornire un'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente (anteprima) nella stringa di connessione.

Identità gestita assegnata dal sistema

L'API REST, portale di Azure e .NET SDK supportano l'uso di un'identità gestita assegnata dal sistema.

Quando ci si connette con un'identità gestita assegnata dal sistema, l'unica modifica alla definizione dell'origine dati è il formato della proprietà "credentials". Specificare il nome del database e un Id risorsa senza chiave o password dell'account. ResourceId deve includere l'ID sottoscrizione di Azure Cosmos DB, il gruppo di risorse e il nome dell'account Azure Cosmos DB.

  • Per le raccolte SQL, il stringa di connessione non richiede "ApiKind".
  • Per le raccolte SQL, aggiungere "IdentityAuthType=AccessToken" se l'accesso basato sui ruoli viene applicato come unico metodo di autenticazione. Non è applicabile per le raccolte MongoDB e Gremlin.
  • Per le raccolte MongoDB, aggiungere "ApiKind=MongoDb" al stringa di connessione e usare un'API REST di anteprima.
  • Per i grafici Gremlin, aggiungere "ApiKind=Gremlin" al stringa di connessione e usare un'API REST di anteprima.

Ecco un esempio di come creare un'origine dati per indicizzare i dati da un account di archiviazione usando l'API REST Crea origine dati e un'identità gestita stringa di connessione. Il formato dell'identità gestita stringa di connessione è lo stesso per l'API REST, .NET SDK e l'portale di Azure.

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

 
}

Identità gestita assegnata dall'utente (anteprima)

L'API REST 2021-04-30-preview supporta le connessioni basate su un'identità gestita assegnata dall'utente. Quando ci si connette con un'identità gestita assegnata dall'utente, vengono apportate due modifiche alla definizione dell'origine dati:

  • In primo luogo, il formato della proprietà "credentials" è il nome del database e un ResourceId senza chiave o password dell'account. ResourceId deve includere l'ID sottoscrizione di Azure Cosmos DB, il gruppo di risorse e il nome dell'account Azure Cosmos DB.

    • Per le raccolte SQL, il stringa di connessione non richiede "ApiKind".
    • Per le raccolte SQL, aggiungere "IdentityAuthType=AccessToken" se l'accesso basato sui ruoli viene applicato come unico metodo di autenticazione. Non è applicabile per le raccolte MongoDB e Gremlin.
    • Per le raccolte MongoDB, aggiungere "ApiKind=MongoDb" alla stringa di connessione
    • Per i grafici Gremlin, aggiungere "ApiKind=Gremlin" alla stringa di connessione.

  • In secondo luogo, si aggiunge una proprietà "identity" che contiene la raccolta di identità gestite assegnate dall'utente. Quando si crea l'origine dati, è necessario specificare un'unica identità gestita assegnata dall'utente. Impostarlo sul tipo "userAssignedIdentities".

Di seguito è riportato un esempio di come creare un oggetto origine dati dell'indicizzatore usando l'anteprima Creare o aggiornare l'API REST dell'origine dati:

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
}

Creare l'indice

L'indice consente di specificare i campi in un documento, gli attributi e altri costrutti che danno forma all'esperienza della ricerca.

Ecco una chiamata all'API REST Create Index con un campo ricercabile booktitle :

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

Creare l'indicizzatore

Un indicizzatore si connette a un'origine dati con un indice di ricerca di destinazione e pianifica l’automatizzazione dell'aggiornamento dei dati. Dopo aver creato l'indice e l'origine dati, è possibile creare ed eseguire l'indicizzatore. Se l'indicizzatore ha esito positivo, la sintassi di connessione e le assegnazioni di ruolo sono valide.

Ecco una chiamata all'API REST Create Indexer con una definizione dell'indicizzatore NoSQL per Azure Cosmos DB. L'indicizzatore viene eseguito quando si invia la richiesta.

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

Risoluzione dei problemi

Se di recente sono state ruotate le chiavi dell'account Azure Cosmos DB, è necessario attendere fino a 15 minuti prima che l'identità gestita stringa di connessione funzioni.

Verificare se l'account Azure Cosmos DB ha accesso limitato alle reti selezionate. È possibile escludere eventuali problemi del firewall provando la connessione senza restrizioni.

Vedi anche