Indicizzare i dati da Azure Cosmos DB for MongoDB per le query in Azure AI Search
Importante
Il supporto dell'API MongoDB è attualmente disponibile in anteprima pubblica nel quadro delle Condizioni supplementari per l'utilizzo. Attualmente l'SDK non è supportato.
Questo articolo illustra come configurare un indicizzatore che importa contenuto da Azure Cosmos DB for MongoDB e lo rende ricercabile in Azure AI Search.
Questo articolo integra Creare un indicizzatore con informazioni specifiche per Cosmos DB. Esso usa le API REST per illustrare un flusso di lavoro a tre passaggi comune a tutti gli indicizzatori: creare un'origine dati, creare un indice, creare un indicizzatore. L'estrazione di dati si verifica all’invio della richiesta Crea indicizzatore.
Poiché la terminologia può talvolta creare confusione, vale la pena notare che l'indicizzazione di Azure Cosmos DB e l'indicizzazione di Azure AI Search sono operazioni diverse. L'indicizzazione in Azure AI Search crea e carica un indice di ricerca nel servizio di ricerca.
Prerequisiti
Registrarsi per l'anteprima per fornire feedback sullo scenario. È possibile accedere automaticamente alla funzionalità dopo l'invio del modulo.
Un account, un database, una raccolta e documenti Azure Cosmos DB. Usare la stessa area per Azure AI Search e per Azure Cosmos DB per ridurre la latenza ed evitare addebiti per la larghezza di banda.
Un criterio di indicizzazione automatica nella raccolta di Azure Cosmos DB impostato su Coerente. Questa è la configurazione predefinita. L'indicizzazione differita non è consigliata e può comportare la mancanza di dati.
Autorizzazioni di lettura. Una stringa di connessione per l'accesso completo include una chiave che concede l'accesso al contenuto, ma se si usano i ruoli di Azure, assicurarsi che l'identità gestita del servizio di ricerca abbia le autorizzazioni del Ruolo Lettore dell'account Cosmos DB.
Un client REST per creare l'origine dati, l'indice e l'indicizzatore.
Limiti
Di seguito sono riportate le limitazioni di questa funzionalità:
Le query personalizzate non sono supportate per specificare il set di dati.
Il nome di colonna
_tsè una parola riservata. Se è necessario questo campo, considerare soluzioni alternative per popolare un indice.L'attributo di MongoDB
$refè una parola riservata. Se è necessario nella raccolta MongoDB, considerare soluzioni alternative per popolare un indice.
Come alternativa a questo connettore, se lo scenario presenta uno di questi requisiti è possibile usare l'SDK o l'API Push o prendere in considerazione l'uso di Azure Data Factory con un indice di Azure AI Search come sink.
Definire l'origine dati
La definizione dell'origine dati specifica i dati da indicizzare e credenziali e criteri per identificare modifiche nei dati. Un’origine dati è definita come risorsa indipendente affinché possa essere usata da più indicizzatori.
Per questa chiamata, specificare una versione dell'API REST di anteprima. È possibile usare 2020-06-30-preview o versione successiva per creare un'origine dati che si connette tramite l'API MongoDB. È consigliabile usare l'API REST di anteprima più recente.
Creare o aggiornare un'origine dati per impostarne la definizione:
POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview Content-Type: application/json api-key: [Search service admin key] { "name": "[my-cosmosdb-mongodb-ds]", "type": "cosmosdb", "credentials": { "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb;" }, "container": { "name": "[cosmos-db-collection]", "query": null }, "dataChangeDetectionPolicy": { "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName": "_ts" }, "dataDeletionDetectionPolicy": null, "encryptionKey": null, "identity": null }Impostare "type" su
"cosmosdb"(obbligatorio).Impostare "credentials" su una stringa di connessione. Nella sezione successiva vengono descritti i formati supportati.
Impostare "container" sulla raccolta. La proprietà "name" è obbligatoria e specifica l'ID della raccolta di database da indicizzare. Per Azure Cosmos DB for MongoDB, "query" non è supportato.
Impostare "dataChangeDetectionPolicy" se i dati sono volatili e si vuole che l'indicizzatore recuperi solo gli elementi nuovi e aggiornati nelle esecuzioni successive.
Impostare "dataDeletionDetectionPolicy" se si vogliono rimuovere i documenti di ricerca da un indice di ricerca quando l'elemento di origine viene eliminato.
Credenziali e stringhe di connessione supportate
Gli indicizzatori possono connettersi a una raccolta usando le connessioni seguenti. Per le connessioni destinate all'API MongoDB, assicurarsi di includere "ApiKind" nella stringa di connessione.
Evitare di inserire numeri di porta nell'URL dell'endpoint. Se si include il numero di porta, la connessione avrà esito negativo.
| Stringa di connessione per l'accesso completo |
|---|
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" } |
| È possibile ottenere la chiave di autenticazione di Cosmos DB dalla pagina dell'account Azure Cosmos DB nel portale di Azure selezionando Stringa di connessione nel riquadro di spostamento sinistro. Assicurarsi di copiare la Password primaria e sostituire il valore di chiave di autenticazione di Cosmos DB con la password. |
| Stringa di connessione dell'identità gestita |
|---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" } |
| Questa stringa di connessione non richiede una chiave dell'account, ma è necessario aver precedentemente configurato un servizio di ricerca per la connessione tramite un'identità gestita e aver creato un'assegnazione di ruolo che concede le autorizzazioni del Ruolo Lettore dell'account Cosmos DB. Per altre informazioni, vedere Configurare una connessione dell'indicizzatore a un database di Azure Cosmos DB usando un'identità gestita. |
Aggiungere campi di ricerca a un indice
In un indice di ricerca, aggiungere campi per accettare i documenti JSON di origine o l'output della proiezione di query personalizzata. Verificare che lo schema dell'indice di ricerca sia compatibile con i dati di origine. Per il contenuto in Azure Cosmos DB, lo schema dell'indice di ricerca deve corrispondere agli elementi di Azure Cosmos DB nell'origine dati.
Creare o aggiornare un indice per definire i campi di ricerca che archivieranno i dati:
POST https://[service name].search.windows.net/indexes?api-version=2024-05-01-preview Content-Type: application/json api-key: [Search service admin key] { "name": "mysearchindex", "fields": [{ "name": "doc_id", "type": "Edm.String", "key": true, "retrievable": true, "searchable": false }, { "name": "description", "type": "Edm.String", "filterable": false, "searchable": true, "sortable": false, "facetable": false, "suggestions": true }] }Creare un campo chiave documento ("chiave": true). Per un indice di ricerca basato su una raccolta MongoDB, la chiave del documento può essere "doc_id", "rid" o un altro campo stringa contenente valori univoci. Purché i nomi dei campi e i tipi di dati siano uguali su entrambi i lati, non sono necessari mapping dei campi.
"doc_id" rappresenta "_id" per l'identificatore di oggetto. Se si specifica un campo "doc_id" nell'indice, l'indicizzatore lo popola con i valori dell'identificatore di oggetto.
"rid" è una proprietà di sistema in Azure Cosmos DB. Se si specifica un campo "rid" nell'indice, l'indicizzatore lo popola con il valore con codifica Base64 della proprietà "rid".
Per qualsiasi altro campo, il campo di ricerca deve avere lo stesso nome definito nella raccolta.
Creare campi aggiuntivi per rendere il contenuto più ricercabile. Per altri dettagli, vedere Creare un indice.
Mapping di tipi di dati
| Tipo di dati JSON | Tipi di campo di Azure AI Search |
|---|---|
| Bool | Edm.Boolean, Edm.String |
| Numeri che rappresentano numeri interi | Edm.Int32, Edm.Int64, Edm.String |
| Numeri che rappresentano numeri a virgola mobile | Edm.Double, Edm.String |
| String | Edm.String |
| Matrici di tipi primitivi, ad esempio ["a", "b", "c"] | Collection(Edm.String) |
| Stringhe che rappresentano date | Edm.DateTimeOffset, Edm.String |
| Oggetti GeoJSON, ad esempio { "type": "Point", "coordinates": [long, lat] } | Edm.GeographyPoint |
| Altri oggetti JSON | N/D |
Configurare ed eseguire l'indicizzatore di Azure Cosmos DB for MongoDB
Dopo aver creato l'indice e l'origine dati, è possibile creare l'indicizzatore. La configurazione dell'indicizzatore specifica gli input, i parametri e le proprietà che controllano i comportamenti della fase di esecuzione.
Creare o aggiornare l'indicizzatore assegnandogli un nome e il riferimento all’origine dati e all'indice di destinazione:
POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview Content-Type: application/json api-key: [search service admin key] { "name" : "[my-cosmosdb-indexer]", "dataSourceName" : "[my-cosmosdb-mongodb-ds]", "targetIndexName" : "[my-search-index]", "disabled": null, "schedule": null, "parameters": { "batchSize": null, "maxFailedItems": 0, "maxFailedItemsPerBatch": 0, "base64EncodeKeys": false, "configuration": {} }, "fieldMappings": [], "encryptionKey": null }Specificare i mapping dei campi se sono presenti differenze nel nome o nel tipo di campo oppure se sono necessarie più versioni di un campo di origine nell'indice di ricerca.
Per ulteriori informazioni su altre proprietà, vedere Creare un indicizzatore.
Un indicizzatore viene eseguito automaticamente al momento della sua creazione. È possibile ovviare a questo problema impostando "disabilitato" su true. Per controllare l'esecuzione dell'indicizzatore, eseguire un indicizzatore su richiesta o inserirlo in una pianificazione.
Controllare lo stato dell'indicizzatore
Per monitorare lo stato dell'indicizzatore e la cronologia di esecuzione, inviare una richiesta Ottieni stato dell’indicizzatore:
GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [admin key]
La risposta include lo stato e il numero di elementi elaborati. Dovrebbe risultare simile all'esempio seguente:
{
"status":"running",
"lastResult": {
"status":"success",
"errorMessage":null,
"startTime":"2022-02-21T00:23:24.957Z",
"endTime":"2022-02-21T00:36:47.752Z",
"errors":[],
"itemsProcessed":1599501,
"itemsFailed":0,
"initialTrackingState":null,
"finalTrackingState":null
},
"executionHistory":
[
{
"status":"success",
"errorMessage":null,
"startTime":"2022-02-21T00:23:24.957Z",
"endTime":"2022-02-21T00:36:47.752Z",
"errors":[],
"itemsProcessed":1599501,
"itemsFailed":0,
"initialTrackingState":null,
"finalTrackingState":null
},
... earlier history items
]
}
La cronologia di esecuzione contiene fino a 50 esecuzioni completate più recenti in ordine cronologico inverso, in modo che l'esecuzione più recente venga visualizzata per prima.
Indicizzazione di documenti nuovi e modificati
Dopo che un indicizzatore ha popolato completamente un indice di ricerca, può essere utile che le esecuzioni successive indicizzino in modo incrementale solo i documenti nuovi e modificati nel database.
Per abilitare l'indicizzazione incrementale, impostare la proprietà "dataChangeDetectionPolicy" nella definizione dell'origine dati. Questa proprietà indica all'indicizzatore quale meccanismo di rilevamento delle modifiche viene usato sui dati.
Per gli indicizzatori di Azure Cosmos DB, l'unico criterio supportato è HighWaterMarkChangeDetectionPolicy che usa la proprietà _ts (timestamp) fornita da Azure Cosmos DB.
L'esempio seguente mostra una definizione dell'origine dati con un criterio di rilevamento delle modifiche:
"dataChangeDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
" highWaterMarkColumnName": "_ts"
},
Indicizzazione di documenti eliminati
Quando si eliminano righe dalla raccolta, in genere le si elimina anche dall'indice di ricerca. Scopo dei criteri di rilevamento dell'eliminazione dei dati è quello di identificare in modo efficace gli elementi di dati eliminati. Attualmente, l'unico criterio supportato è il criterio Soft Delete (l'eliminazione è contrassegnata da un tipo di flag), specificato nella definizione dell'origine dati come segue:
"dataDeletionDetectionPolicy"": {
"@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
"softDeleteColumnName" : "the property that specifies whether a document was deleted",
"softDeleteMarkerValue" : "the value that identifies a document as deleted"
}
Se si usa una query personalizzata, assicurarsi che la proprietà a cui fa riferimento softDeleteColumnName sia proiettata dalla query.
L'esempio seguente crea un'origine dati con criteri di eliminazione temporanea:
POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]
{
"name": ["my-cosmosdb-mongodb-ds]",
"type": "cosmosdb",
"credentials": {
"connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDB"
},
"container": { "name": "[my-cosmos-collection]" },
"dataChangeDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"highWaterMarkColumnName": "_ts"
},
"dataDeletionDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
"softDeleteColumnName": "isDeleted",
"softDeleteMarkerValue": "true"
}
}
Passaggi successivi
Ora è possibile controllare come eseguire l'indicizzatore, monitorare lo stato o pianificare l'esecuzione dell'indicizzatore. Gli articoli seguenti riguardano gli indicizzatori che eseguono il pull di contenuto da Azure Cosmos DB: