Indicizzazione dei dati di Azure Cosmos DB per MongoDB per le query in Azure AI Search (anteprima)

Il Azure Cosmos DB per l'indicizzatore MongoDB (anteprima) importa il contenuto da Azure Cosmos DB per MongoDB e lo rende ricercabile in Azure AI Search.

Questo articolo integra l'articolo Creare un indicizzatore con informazioni specifiche di Cosmos DB. Usa le API REST per illustrare un flusso di lavoro in tre parti comune a tutti gli indicizzatori: creare un'origine dati, creare un indice, creare un indicizzatore. L'estrazione dei dati si verifica quando si invia la richiesta Crea indicizzatore.

Poiché la terminologia può generare confusione, vale la pena notare che Azure Cosmos DB l'indicizzazione e Azure AI Search l'indicizzazione sono operazioni diverse. L'indicizzazione in Azure AI Search crea e carica un indice di ricerca nel servizio di ricerca.

Prerequisiti

• Completare il modulo di registrazione dell'anteprima dell'indicizzatore. La registrazione viene approvata automaticamente.

• Un account Azure Cosmos DB, una banca dati, una raccolta e documenti. Usare la stessa area per Azure AI Search e Azure Cosmos DB per ridurre la latenza ed evitare addebiti per la larghezza di banda.

• Un criterio di indicizzazione automatico nella raccolta Azure Cosmos DB, impostato su Consistent. Questa impostazione è la configurazione predefinita. L'indicizzazione lazy non è consigliata e potrebbe 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.

• Client REST per creare l'origine dati, l'indice e l'indicizzatore.

Limitazioni

Queste sono le limitazioni di questa funzionalità:

• Le query personalizzate non sono supportate per specificare il set di dati.

• Il nome _ts della colonna è una parola riservata. Se è necessario questo campo, prendere in considerazione soluzioni alternative per popolare un indice.

• L'attributo $ref MongoDB è una parola riservata. Se hai bisogno di questo nella tua raccolta MongoDB, prendi in considerazione soluzioni alternative per riempire un indice.

In alternativa a questo connettore, se lo scenario ha uno di questi requisiti, è possibile usare l'API Push API/SDK o prendere in considerazione Azure Data Factory con un indice Azure AI Search come sink.

Definire l'origine dati

La definizione dell'origine dati specifica i dati da indicizzare, credenziali e criteri per identificare le modifiche nei dati. Un'origine dati viene definita come risorsa indipendente in modo che possa essere usata da più indicizzatori.

Per questa chiamata, specificare una versione di anteprima dell'API REST per creare un'origine dati che si connette tramite l'API MongoDB. È possibile usare 2020-06-30-preview o versioni successive. È consigliabile usare l'API REST di anteprima più recente.

1. Creare o aggiornare un'origine dati per impostarne la definizione:

   POST https://[service name].search.windows.net/datasources?api-version=2026-08-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]"
     },
     "dataChangeDetectionPolicy": {
       "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
       "highWaterMarkColumnName": "_ts"
     },
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
   }
   

2. Impostare "type" su "cosmosdb" (obbligatorio).

3. Impostare "credentials" su una stringa di connessione. Nella sezione successiva vengono descritti i formati supportati.

4. Impostare "container" sulla raccolta. La proprietà "name" è obbligatoria e specifica l'ID della raccolta di database da indicizzare. Per Azure Cosmos DB per MongoDB, la "query" non è supportata.

5. Impostare "dataChangeDetectionPolicy" se i dati sono volatili e si vuole che l'indicizzatore rilevi solo gli elementi nuovi e aggiornati nelle esecuzioni successive.

6. Impostare "dataDeletionDetectionPolicy" se si desidera 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" nel stringa di connessione.

Evitare numeri di porta nell'URL dell'endpoint. Se si include il numero di porta, la connessione non riesce.

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 Azure Cosmos DB nell'origine dati.

1. Creare o aggiornare un indice per definire i campi di ricerca in cui sono archiviati i dati:

   POST https://[service name].search.windows.net/indexes?api-version=2026-08-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
       }]
   }
   

2. Creare un campo chiave del 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 che contiene 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 dell'oggetto. Se si specifica un campo "doc_id" nell'indice, l'indicizzatore lo popola con i valori dell'identificatore dell'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.

3. Creare campi aggiuntivi per un contenuto più ricercabile. Per informazioni dettagliate, vedere Creare un indice .

Mapping dei tipi di dati

Configurare ed eseguire il Azure Cosmos DB per l'indicizzatore 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 di runtime.

1. Creare o aggiornare un indicizzatore assegnando un nome e facendo riferimento all'origine dati e all'indice di destinazione:

   POST https://[service name].search.windows.net/indexers?api-version=2026-08-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
   }
   

2. Specificare i mapping dei campi se sono presenti differenze nel nome o nel tipo di campo o se sono necessarie più versioni di un campo di origine nell'indice di ricerca.

3. Per altre informazioni sulle altre proprietà, vedere Creare un indicizzatore .

Un indicizzatore viene eseguito automaticamente quando viene creato. È possibile evitare 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 Get Indexer Status :To monitor the indexer status and execution history, send a Get Indexer Status request:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-08-01-preview
  Content-Type: application/json  
  api-key: [admin key]

La risposta include lo stato e il numero di elementi elaborati. Dovrebbe essere 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 delle esecuzioni completate più di recente, ordinate in ordine cronologico inverso in modo che l'esecuzione più recente venga prima.

Indicizzazione di documenti nuovi e modificati

Dopo che un indicizzatore ha popolato completamente un indice di ricerca, è possibile che l'indicizzatore successivo venga eseguito per indicizzare 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 Azure Cosmos DB, l'unico criterio supportato è il HighWaterMarkChangeDetectionPolicy usando la proprietà _ts (timestamp) fornita da Azure Cosmos DB.

L'esempio seguente mostra una definizione di origine dati con un criterio di rilevamento delle modifiche:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
},

Indicizzazione di documenti eliminati

Quando le righe vengono eliminate dalla raccolta, in genere si desidera eliminare anche tali righe dall'indice di ricerca. Lo scopo di un criterio di rilevamento dell'eliminazione dei dati è identificare in modo efficiente gli elementi di dati eliminati. Attualmente, l'unica politica supportata è la Soft Delete politica (l'eliminazione è contrassegnata con un flag di qualche tipo), specificata nella definizione dell'origine dati di seguito.

"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=2026-08-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 si applicano agli indicizzatori che estraggono il contenuto da Azure Cosmos DB:

• Impostare una connessione dell'indicizzatore a un database di Azure Cosmos DB usando un'identità gestita
• Indicizzare set di dati di grandi dimensioni
• Indexer accesso al contenuto protetto dalle funzionalità di sicurezza di rete Azure