Indexar dados do Azure Cosmos DB para MongoDB para consultas no Azure AI Search
Importante
Atualmente, o suporte à API do MongoDB está em visualização pública sob os Termos de Uso complementares. No momento, não há suporte a SDK.
Neste artigo, saiba como configurar um indexador que importa conteúdo do Azure Cosmos DB para MongoDB e o torna pesquisável no Azure AI Search.
Este artigo complementa o artigo Criar um indexador com informações específicas do Cosmos DB. Ele usa as APIs REST para demonstrar um fluxo de trabalho de três partes comum a todos os indexadores: criar uma fonte de dados, criar um índice e criar um indexador. A extração de dados ocorre quando você envia a solicitação Criar Indexador.
Como a terminologia pode ser confusa, vale a pena observar que a indexação do Azure Cosmos DB e a indexação do Azure AI Search são operações diferentes. A indexação no Azure AI Search cria e carrega um índice de pesquisa em seu serviço de pesquisa.
Pré-requisitos
Registre-se para a versão prévia para fornecer comentários sobre o cenário. Você pode acessar o recurso automaticamente após o envio do formulário.
Uma conta, um banco de dados, uma coleção e documentos do Azure Cosmos DB. Use a mesma região para o Azure AI Search e o Azure Cosmos DB para menor latência e para evitar encargos de largura de banda.
Uma política de indexação automática na coleção do Azure Cosmos DB, definida como Consistente. Essa é a configuração padrão. A indexação lenta não é recomendada e pode resultar em dados ausentes.
Permissões de leitura. Uma cadeia de conexão de "acesso completo" inclui uma chave que permite acesso ao conteúdo, mas se você estiver usando funções do Azure, verifique se a identidade gerenciada do serviço de pesquisa tem as permissões Função de Leitor da 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 desse recurso:
Não há suporte para consultas personalizadas para especificar o conjunto de dados.
O nome da coluna
_tsé uma palavra reservada. Se você precisar desse campo, considere soluções alternativas para preencher um índice.O atributo
$refMongoDB é uma palavra reservada. Se você precisar disso em sua coleção do MongoDB, considere soluções alternativas para preencher um índice.
Como alternativa a esse conector, se o cenário tiver algum desses requisitos, você poderá usar a API/SDK por Push ou considerar Azure Data Factory com um índice do Azure AI Search como coletor.
Definir a fonte de dados
A definição da fonte de dados especifica os dados a serem indexados, as credenciais e as políticas para identificar alterações nos dados. Uma fonte de dados é definida como um recurso independente para que possa ser usada por vários indexadores.
Para esta chamada, especifique uma versão prévia da API REST. Você pode usar 2020-06-30-versão prévia ou posterior para criar uma fonte de dados que se conecta por meio da API MongoDB. Recomendamos a API REST de visualização mais recente.
Crie ou atualize uma fonte de dados para configurar sua definição:
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 }Defina "type" como
"cosmosdb"(obrigatório).Defina "credentials" como a cadeia de conexão. A próxima seção descreve os formatos compatíveis.
Defina "container" como a coleção. A propriedade "name" é necessária e especifica a ID da coleção de banco de dados a ser indexada. Para o Azure Cosmos DB for MongoDB, não há suporte para "consulta".
Defina "dataChangeDetectionPolicy" se os dados forem voláteis e você quiser que o indexador selecione apenas os itens novos e atualizados nas execuções seguintes.
Defina "dataDeletionDetectionPolicy" se desejar remover documentos de pesquisa de um índice de pesquisa quando o item de origem for excluído.
Credenciais e cadeias de conexão com suporte
Os indexadores podem se conectar a uma coleção usando as conexões a seguir. Para conexões direcionadas à API do MongoDB, inclua "ApiKind" na cadeia de conexão.
Evite usar números de porta na URL do ponto de extremidade. Se você incluir o número da porta, a conexão falhará.
| Cadeia de conexão de acesso completo |
|---|
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" } |
| Você pode obter a chave de autenticação do Cosmos DB na página da conta do Azure Cosmos DB no portal do Azure selecionando Cadeia de conexão no painel de navegação à esquerda. Copie a Senha Primária e substitua o valor da chave de autenticação do Cosmos DB por ela. |
| Cadeia de conexão de identidade gerenciada |
|---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" } |
| Essa cadeia de conexão não exige uma chave de conta, mas você precisa ter configurado anteriormente um serviço de pesquisa para se conectar usando uma identidade gerenciada e ter criado uma atribuição de função que conceda permissões de Função de Leitor de Conta do Cosmos DB. Confira Configurar uma conexão do indexador com um banco de dados do Azure Cosmos DB usando uma identidade gerenciada para saber mais. |
Adicionar campos de pesquisa a um índice
Em um índice de pesquisa, adicione campos para aceitar os documentos JSON de origem ou a saída da projeção de consulta personalizada. Verifique se o esquema de índice de pesquisa é compatível com os dados de origem. Para o conteúdo no Azure Cosmos DB, o esquema de índice de pesquisa deve corresponder aos itens do Azure Cosmos DB na fonte de dados.
Crie ou atualize um índice para definir os campos de pesquisa que armazenarão os dados:
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 }] }Crie um campo de chave do documento ("key": true). Em um índice de pesquisa baseado em uma coleção do MongoDB, a chave do documento pode ser "doc_id", "rid" ou algum outro campo de cadeia de caracteres que contém valores exclusivos. Como os nomes dos campos e os tipos de dados são os mesmos nos dois lados, não é necessário nenhum mapeamento de campo.
A "doc_id" representa a "_id" para o identificador de objeto. Se você especificar um campo para "doc_id" no índice, o indexador o preencherá com os valores do identificador de objeto.
"rid" é uma propriedade do sistema no Azure Cosmos DB. Se você especificar um campo para "rid" no índice, o indexador o preencherá com o valor codificado em base64 da propriedade "rid".
Em outros campos, seu campo de pesquisa deve ter o mesmo nome definido na coleção.
Crie campos adicionais para obter um conteúdo mais pesquisável. Confira Criar um índice para obter detalhes.
Mapeamento de tipos de dados
| Tipo de dados JSON | Tipos de campo do Azure AI Search |
|---|---|
| Bool | Edm.Boolean, Edm.String |
| Números que se parecem com inteiros | Edm.Int32, Edm.Int64, Edm.String |
| Números que se parecem com pontos flutuantes | Edm.Double, Edm.String |
| String | Edm.String |
| Matrizes de tipos primitivos, como ["a", "b" e "c"] | Collection(Edm.String) |
| Cadeias de caracteres que se parecem com datas | Edm.DateTimeOffset, Edm.String |
| Objetos GeoJSON, por exemplo, { "type": "Point", "coordinates": [long, lat] } | Edm.GeographyPoint |
| Outros objetos JSON | N/D |
Configurar e executar o indexador do Azure Cosmos DB para MongoDB
Uma vez que o índice e a fonte de dados forem criados, será possível criar o indexador. A configuração do indexador especifica as entradas, os parâmetros e as propriedades que controlam os comportamentos de tempo de execução.
Crie ou atualize um indexador dando um nome a ele e referenciando a fonte de dados e o índice de destino:
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 }Especifique mapeamentos de campo se houver diferenças no nome ou tipo de campo, ou se você precisar de várias versões de um campo de origem no índice de pesquisa.
Confira Criar um indexador para obter mais informações sobre outras propriedades.
Um indexador é executado automaticamente depois de criado. Você pode evitar isso definindo "desabilitado" como verdadeiro. Para controlar a execução do indexador, execute um indexador sob demanda ou coloque-o em um agendamento.
Checar o status do indexador
Para monitorar o histórico de execuções e o status do indexador, envie uma solicitação Obter Status do Indexador:
GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [admin key]
A resposta inclui o status e o número de itens processados. Ela deve ser parecida com o 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 execuções mais recentes, classificadas em ordem cronológica inversa, de modo que a execução mais recente apareça em primeiro lugar.
Como indexar documentos novos e alterados
Depois que um indexador preencher completamente um índice de pesquisa, o ideal será que o indexador seguinte seja executado para indexar de maneira incremental apenas os documentos novos e alterados no banco de dados.
Para habilitar a indexação incremental, defina a propriedade "dataChangeDetectionPolicy" na definição da fonte de dados. Essa propriedade informa o indexador de que o mecanismo de controle de alterações é usado nos dados.
Para indexadores do Azure Cosmos DB, a única política com suporte é a HighWaterMarkChangeDetectionPolicy que usa a propriedade _ts (carimbo de data/hora) fornecida pelo Azure Cosmos DB.
O seguinte exemplo mostra uma definição de fonte de dados com uma política de detecção de alteração:
"dataChangeDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
" highWaterMarkColumnName": "_ts"
},
Indexando documentos excluídos
Quando as linhas são excluídas da coleção, normalmente, você também deseja excluí-las do índice de pesquisa. A finalidade de uma política de detecção de exclusão de dados é identificar de maneira eficaz dados excluídos. Atualmente, a única política com suporte é a política Soft Delete (a exclusão recebe algum tipo de marcador), que é especificada na definição de 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 você estiver usando uma consulta personalizada, garanta que a propriedade referenciada por softDeleteColumnName seja projetada pela consulta.
O seguinte exemplo cria uma fonte de dados com uma política de exclusão reversível:
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"
}
}
Próximas etapas
Você já pode controlar como executar o indexador, monitorar o status ou agendar a execução do indexador. Os seguintes artigos se aplicam aos indexadores que efetuam pull do conteúdo do Azure Cosmos DB: