Dados de índice do Azure Cosmos DB para MongoDB para consultas no Azure AI Search
Importante
O suporte à API do MongoDB está atualmente em visualização pública sob Termos de Uso suplementares. Atualmente, 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 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, 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 na Pesquisa de IA do Azure cria e carrega um índice de pesquisa no seu serviço de pesquisa.
Pré-requisitos
Registre-se para a visualização para fornecer feedback sobre o cenário. Você pode acessar o recurso automaticamente após o envio do formulário.
Uma conta, banco de dados, coleção e documentos do Azure Cosmos DB. Use a mesma região para o Azure AI Search e o Azure Cosmos DB para obter latência mais baixa e evitar cobranças de largura de banda.
Uma política de indexação automática na coleção do Azure Cosmos DB, definida como Consistente. Esta é a configuração predefinida. A indexação lenta não é recomendada e pode resultar na falta de dados.
Permissões de leitura. Uma cadeia de conexão de "acesso total" inclui uma chave que concede acesso ao conteúdo, mas se você estiver usando funções do Azure, verifique se a identidade gerenciada do serviço de pesquisa tem permissões de Função 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 deste recurso:
Não há suporte para consultas personalizadas para especificar o conjunto de dados.
O nome
_tsda coluna é uma palavra reservada. Se 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 MongoDB, considere soluções alternativas para preencher um índice.
Como alternativa a esse conector, se seu cenário tiver qualquer um desses requisitos, você poderá usar a API/SDK por push ou considerar o Azure Data Factory com um índice de Pesquisa de IA do Azure como coletor.
Definir a fonte de dados
A definição da fonte de dados especifica os dados a serem indexados, 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 vários indexadores.
Para esta chamada, especifique uma versão de visualização da API REST. Você pode usar 2020-06-30-preview ou posterior para criar uma fonte de dados que se conecta por meio da API do MongoDB. Recomendamos a API REST de visualização mais recente.
Crie ou atualize uma fonte de dados para definir 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 "credenciais" como uma cadeia de conexão. A próxima seção descreve os formatos suportados.
Defina "container" para 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 para MongoDB, "consulta" não é suportada.
Defina "dataChangeDetectionPolicy" se os dados forem voláteis e você quiser que o indexador pegue apenas os itens novos e atualizados em execuções subsequentes.
Defina "dataDeletionDetectionPolicy" se quiser remover documentos de pesquisa de um índice de pesquisa quando o item de origem for excluído.
Credenciais e cadeias de conexão suportadas
Os indexadores podem se conectar a uma coleção usando as seguintes conexões. Para conexões destinadas à API do MongoDB, certifique-se de incluir "ApiKind" na cadeia de conexão.
Evite números de porta no URL do ponto de extremidade. Se você incluir o número da porta, a conexão falhará.
| Cadeia de conexão de acesso total |
|---|
{ "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 esquerdo. Certifique-se de copiar a Senha Primária e substituir 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 requer uma chave de conta, mas você deve ter configurado anteriormente um serviço de pesquisa para se conectar usando uma identidade gerenciada e criado uma atribuição de função que conceda permissões de Função de Leitor de Conta do Cosmos DB. Consulte Configurando uma conexão de indexador com um banco de dados do Azure Cosmos DB usando uma identidade gerenciada para obter mais informações. |
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 de sua projeção de consulta personalizada. Verifique se o esquema de índice de pesquisa é compatível com os dados de origem. Para conteúdo no Azure Cosmos DB, seu esquema de índice de pesquisa deve corresponder aos itens do Azure Cosmos DB em sua fonte de dados.
Crie ou atualize um índice para definir campos de pesquisa que armazenarão 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 de documento ("chave": true). Para um índice de pesquisa baseado em uma coleção MongoDB, a chave do documento pode ser "doc_id", "rid" ou algum outro campo de cadeia de caracteres que contenha valores exclusivos. Desde que os nomes de campo e os tipos de dados sejam os mesmos em ambos os lados, não são necessários mapeamentos de campo.
"doc_id" representa "_id" para o identificador de objeto. Se você especificar um campo de "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 de "rid" no índice, o indexador o preencherá com o valor codificado em base64 da propriedade "rid".
Para qualquer outro campo, o campo de pesquisa deve ter o mesmo nome definido na coleção.
Crie campos adicionais para mais conteúdo pesquisável. Consulte Criar um índice para obter detalhes.
Mapeando tipos de dados
| Tipo de dados JSON | Tipos de campo do Azure AI Search |
|---|---|
| Bool | Edm.Booleano, Edm.String |
| Números que se parecem com números 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", "c"] | Collection(Edm.String) |
| Cadeias de caracteres que se parecem com datas | Edm.DateTimeOffset, Edm.String |
| Objetos GeoJSON como { "type": "Point", "coordinates": [long, lat] } | Edm.GeographyPoint |
| Outros objetos JSON | N/A |
Configurar e executar o indexador do Azure Cosmos DB para MongoDB
Depois que o índice e a fonte de dados forem criados, você estará pronto para criar o indexador. A configuração do indexador especifica as entradas, parâmetros e propriedades que controlam os comportamentos de tempo de execução.
Crie ou atualize um indexador dando-lhe um nome e fazendo referência à fonte de dados e ao í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 precisar de várias versões de um campo de origem no índice de pesquisa.
Consulte Criar um indexador para obter mais informações sobre outras propriedades.
Um indexador é executado automaticamente quando é criado. Você pode evitar isso definindo "desativado" como true. Para controlar a execução do indexador, execute um indexador sob demanda ou coloque-o em uma programação.
Verificar o estado do indexador
Para monitorar o status do indexador e o histórico de execução, 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. Deve ser semelhante 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ção contém até 50 das execuções concluídas mais recentemente, que são classificadas na ordem cronológica inversa para que a execução mais recente venha primeiro.
Indexação de documentos novos e alterados
Depois que um indexador tiver preenchido totalmente um índice de pesquisa, talvez você queira que as execuções subsequentes do indexador indexem incrementalmente apenas os documentos novos e alterados em seu banco de dados.
Para habilitar a indexação incremental, defina a propriedade "dataChangeDetectionPolicy" na definição da fonte de dados. Essa propriedade informa ao indexador qual mecanismo de controle de alterações é usado em seus dados.
Para indexadores do Azure Cosmos DB, a única política com suporte é o HighWaterMarkChangeDetectionPolicy uso da propriedade (carimbo _ts de data/hora) fornecida pelo Azure Cosmos DB.
O exemplo a seguir 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 eliminados
Quando as linhas são excluídas da coleção, normalmente você também deseja excluir essas linhas do índice de pesquisa. O objetivo de uma política de deteção de exclusão de dados é identificar com eficiência os itens de dados excluídos. Atualmente, a única política suportada é a Soft Delete política (a exclusão é marcada com um sinalizador de algum tipo), que é especificada na definição da fonte de dados da seguinte maneira:
"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, verifique se a propriedade referenciada por é projetada pela softDeleteColumnName consulta.
O exemplo a seguir cria uma fonte de dados com uma política de exclusão suave:
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óximos passos
Agora você pode controlar como executar o indexador, monitorar o status ou agendar a execução do indexador. Os seguintes artigos se aplicam a indexadores que extraem conteúdo do Azure Cosmos DB: