Indexar dados do Azure Cosmos DB para MongoDB para consultas no Pesquisa de IA do Azure (preview)

O indexador Azure Cosmos DB for MongoDB (pré-visualização) importa conteúdo do Azure Cosmos DB para MongoDB e torna-o pesquisável no Pesquisa de IA do Azure.

Este artigo complementa Criar um indexador com informação específica para o Cosmos DB. Utiliza as APIs REST para demonstrar um fluxo de trabalho em três partes comum a todos os indexadores: criar uma fonte de dados, criar um índice, criar um indexador. A extração de dados ocorre quando submete o pedido Create Indexer.

Como a terminologia pode ser confusa, é importante notar que a indexação em Azure Cosmos DB e a indexação em Pesquisa de IA do Azure são operações distintas. Indexar no Pesquisa de IA do Azure cria e carrega um índice de pesquisa no seu serviço de pesquisa.

Pré-requisitos

• Preencha o formulário de registo de pré-visualização do indexador. O registo é aprovado automaticamente.

• Uma conta Azure Cosmos DB, base de dados, coleção e documentos. Use a mesma região tanto para o Pesquisa de IA do Azure como para o Azure Cosmos DB para menor latência e para evitar cobranças de largura de banda.

• Uma política de indexação automática na coleção Azure Cosmos DB, definida para Consistente. Esta configuração é a padrão. Indexação preguiçosa não é recomendada e pode resultar em dados em falta.

• Ler permissões. Uma cadeia de conexão de "acesso total" inclui uma chave que concede acesso ao conteúdo, mas se estiveres a usar funções do Azure, certifica-te de que a identidade gerida do serviço de pesquisa tem permissões de Leitor de Conta do Cosmos DB.

• Um cliente REST para criar a fonte de dados, o índice e o indexador.

Limitações

Estas são as limitações desta funcionalidade:

• Não são suportadas consultas personalizadas para especificar o conjunto de dados.

• O nome _ts da coluna é uma palavra reservada. Se precisar deste campo, considere soluções alternativas para preencher um índice.

• O atributo $ref MongoDB é uma palavra reservada. Se precisar disto na sua coleção MongoDB, considere soluções alternativas para preencher um índice.

Como alternativa a este conector, se o teu cenário tiver algum desses requisitos, podes usar a API/SDK> ou considerar Azure Data Factory com um índice Pesquisa de IA do Azure como sumidouro.

Defina a fonte de dados

A definição da fonte de dados especifica os dados a indexar, credenciais e políticas para identificar alterações nos dados. Uma fonte de dados é definida como um recurso independente para que possa ser usada por múltiplos indexadores.

Para esta chamada, especifique uma versão de pré-visualização da API REST para criar uma fonte de dados que se ligue através da API do MongoDB. Podes usar 2020-06-30-preview ou mais tarde. Recomendamos a mais recente API REST de pré-visualização.

1. Crie ou atualize uma fonte de dados para definir a sua definição:

   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. Defina "tipo" para "cosmosdb" (obrigatório).

3. Defina "credenciais" para uma string de conexão. A secção seguinte descreve os formatos suportados.

4. Defina "contentor" para a coleção. A propriedade "nome" é obrigatória e especifica o ID da coleção da base de dados a ser indexada. No Azure Cosmos DB para MongoDB, "query" não é suportado.

5. Defina "dataChangeDetectionPolicy" se os dados estiverem voláteis e quiser que o indexador detete apenas os itens novos e atualizados nas execuções seguintes.

6. Define "dataDeletionDetectionPolicy" se quiseres remover documentos de pesquisa de um índice de pesquisa quando o item de origem for eliminado.

Credenciais suportadas e cadeias de ligação

Os indexadores podem ligar-se a uma coleção usando as seguintes ligações. Para ligações que visam a API MongoDB, certifique-se de incluir "ApiKind" na cadeia de ligação.

Evite números de porta na URL do endpoint. Se você incluir o número da porta, a conexão falhará.

Adicionar campos de pesquisa a um índice

Num índice de pesquisa, adicione campos para aceitar os documentos JSON de origem ou a saída da sua projeção personalizada de consulta. Certifique-se de que o esquema do índice de pesquisa é compatível com os dados de origem. Para conteúdo no Azure Cosmos DB, o seu esquema de índice de pesquisa deve corresponder aos itens do Azure Cosmos DB na sua fonte de dados.

1. Crie ou atualize um índice para definir campos de pesquisa que armazenam dados:

   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. Crie um campo de chave de documento ("chave": verdadeiro). Para um índice de pesquisa baseado numa coleção MongoDB, a chave do documento pode ser "doc_id", "rid" ou outro campo de cadeia que contenha valores únicos. Desde que os nomes dos campos e os tipos de dados sejam os mesmos em ambos os lados, não é necessário mapeamento de campos.

   • "doc_id" representa "_id" para o identificador do objeto. Se especificar um campo de "doc_id" no índice, o indexador preenche-o com os valores do identificador do objeto.

   • "rid" é uma propriedade do sistema no Azure Cosmos DB. Se especificar um campo "rid" no índice, o indexador preenche-o com o valor codificado base64 da propriedade "rid".

   • Para qualquer outro campo, o teu campo de pesquisa deve ter o mesmo nome definido na coleção.

3. Crie campos adicionais para conteúdos mais pesquisáveis. Consulte Criar um índice para mais detalhes.

Mapeamento dos tipos de dados

Configure e executar o indexador Azure Cosmos DB para MongoDB

Depois de criados o índice e a fonte de dados, está pronto para criar o indexador. A configuração do indexador especifica as entradas, parâmetros e propriedades que controlam os comportamentos em tempo de execução.

1. Crie ou atualize um indexador atribuindo-lhe um nome e referenciando a fonte de dados e o índice alvo:

   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. Especifique mapeamentos de campos se existirem diferenças no nome ou tipo do campo, ou se precisar de múltiplas versões de um campo de origem no índice de pesquisa.

3. Consulte Criar um indexador para mais informações sobre outras propriedades.

Um indexador corre automaticamente quando é criado. Podes evitar isto definindo "desabilitado" como verdadeiro. Para controlar a execução do indexador, execute um indexador a pedido ou coloque-o num calendário.

Verificar o estado do indexador

Para monitorizar o estado do indexador e o histórico de execução, envie um pedido Get Indexer Status :

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

A resposta inclui o estado e o número de itens processados. Deverá assemelhar-se ao seguinte exemplo:

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

O histórico de execuções contém até 50 das execuções mais recentemente concluídas, que estão ordenadas por ordem cronológica inversa para que a execução mais recente venha primeiro.

Indexação de documentos novos e alterados

Depois de um indexador preencher totalmente um índice de pesquisa, pode querer que execuções subsequentes indexem incrementalmente apenas os documentos novos e alterados na sua base de dados.

Para permitir a indexação incremental, defina a propriedade "dataChangeDetectionPolicy" na definição da sua fonte de dados. Esta propriedade indica ao indexador qual o mecanismo de acompanhamento de alterações utilizado nos seus dados.

Para Azure Cosmos DB indexadores, a única política suportada é a HighWaterMarkChangeDetectionPolicy usando a propriedade _ts (carimbo temporal) fornecida pela Azure Cosmos DB.

O exemplo seguinte mostra uma definição de fonte de dados com uma política de deteção de alterações:

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

Indexação de documentos apagados

Quando as linhas são eliminadas da coleção, normalmente queres apagar essas linhas também do índice de pesquisa. O objetivo de uma política de deteção de eliminação de dados é identificar eficientemente os itens de dados eliminados. Atualmente, a única política suportada é a Soft Delete política (a eliminação é marcada com algum tipo de flag), que é especificada na definição da fonte de dados da seguinte forma:

"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 estiveres a usar uma consulta personalizada, certifica-te de que a propriedade referenciada por softDeleteColumnName é projetada pela consulta.

O exemplo seguinte cria uma fonte de dados com uma política de eliminação suave:

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

Próximos passos

Agora pode controlar como executa o indexador, monitoriza o estado ou agenda a execução do indexador. Os seguintes artigos aplicam-se a indexadores que extraem conteúdo do Azure Cosmos DB:

• Configure uma ligação indexadora a uma base de dados Azure Cosmos DB usando uma identidade gerida
• Indexar conjuntos de dados grandes
• Acesso do indexador a conteúdos protegidos pelas funcionalidades de segurança de rede da Azure