Adicionar, atualizar ou excluir documentos (Azure Cognitive Search API REST)

Você pode importar documentos de pesquisa para um índice especificado usando HTTP POST. Para um grande número de atualizações, o envio em lote de documentos (até 1.000 documentos por lote ou cerca de 16 MB por lote) é recomendado e melhorará significativamente o desempenho da indexação.

POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]   
  Content-Type: application/json   
  api-key: [admin key]  

Para fontes de dados do Azure com suporte, os indexadores oferecem uma alternativa mais simples para adicionar e atualizar documentos. Para obter mais informações, confira Operações do indexador.

Parâmetros de URI

Parâmetro Descrição
nome do serviço Obrigatórios. Defina isso como o nome exclusivo definido pelo usuário do serviço de pesquisa.
nome do índice Necessário no URI, especificando qual índice publicar documentos. Só é possível postar documentos em um índice por vez.
api-version Obrigatórios. A versão estável atual é api-version=2020-06-30. Consulte versões da API para obter mais versões.

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionais

Campos Descrição
Tipo de conteúdo Obrigatórios. Defina-o como application/json
chave de API Obrigatórios. Uma cadeia de caracteres exclusiva gerada pelo sistema que autentica a solicitação para o serviço de pesquisa. Carregar documentos requer uma chave de API de administrador. Você pode obter chaves do portal do Azure. Para obter mais informações, consulte Localizar chaves existentes.

Corpo da solicitação

O corpo da solicitação contém um ou mais documentos a serem indexados. Os documentos são identificados por uma chave exclusiva que diferencia maiúsculas de minúsculas. Cada documento está associado a uma ação: "carregar", "excluir", "mesclar" ou "mergeOrUpload". As solicitações de carregamento devem incluir os dados do documento como um conjunto de pares de chave/valor.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (key/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}  
Propriedade Descrição
@search.action Obrigatórios. Os valores válidos são "upload", "delete", "merge" ou "mergeOrUpload". O padrão é "carregar". Você pode combinar ações, uma por documento, no mesmo lote.

"upload": uma ação de upload é semelhante a um 'upsert' em que o documento será inserido se ele for novo e atualizado/substituído se existir. Todos os campos são substituídos no caso de atualização.

"delete": Delete remove o documento especificado do índice. Qualquer campo especificado em uma operação de exclusão, diferente do campo de chave, será ignorado. Se você quiser remover um campo individual de um documento, use merge e defina o campo explicitamente como null.

"mergeOrUpload": essa ação se comporta como mesclagem se já existir um documento com a chave fornecida no índice. Se o documento não existir, ele se comportará como carregar com um novo documento.

"mesclagem": A mesclagem atualiza um documento existente com os campos especificados. Se o documento não existir, a mesclagem falhará. Qualquer campo que você especificar em uma mesclagem substituirá o campo existente no documento. Isso também se aplica a coleções de tipos primitivos e complexos.

Em coleções primitivas, se o documento contiver um campo Tags do tipo Collection(Edm.String) com um valor de ["budget"], e você executar uma mesclagem com um valor ["economy", "pool"] para Tag, o valor final do campo Marcas será ["economy", "pool"]. Ele não poderá ser [“budget”, “economy”, “pool”].

Em coleções complexas, se o documento contiver um campo de coleção complexo chamado Salas com um valor de [{ "Type": "Budget Room", "BaseRate": 75.0 }], e você executa uma mesclagem com um valor de [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], o valor final do campo Salas será [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Ele não será nenhum dos seguintes:
[{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (acréscimo de elementos)
[{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (mesclar elementos na ordem e acrescentar quaisquer extras)
key_field_name Obrigatórios. Uma definição de campo no índice que serve como a chave do documento e contém apenas valores exclusivos. As chaves do documento só podem conter letras, números, traços ("-"), sublinhados ("_") e sinais iguais ("=") e diferenciam maiúsculas de minúsculas. Para obter mais informações, consulte Regras de nomenclatura.
field_name Obrigatórios. Pares nome-valor, em que o nome do campo corresponde a um nome de campo na definição de índice. O valor é definido pelo usuário, mas deve ser válido para o tipo de campo.

Resposta

Código de status: 200 é retornado para uma resposta bem-sucedida, o que significa que todos os itens foram armazenados com durabilidade e começarão a ser indexados. A indexação é executada em segundo plano e disponibiliza novos documentos (isto é, consultáveis e pesquisáveis) alguns segundos após a conclusão da operação de indexação. O atraso específico depende da carga do serviço.

A indexação bem-sucedida é indicada pela propriedade de status que está sendo definida como true para todos os itens, bem como a propriedade statusCode que está sendo definida como 201 (para documentos recém-carregados) ou 200 (para documentos mesclados ou excluídos):

{
  "value": [
    {
      "key": "unique_key_of_new_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 201
    },
    {
      "key": "unique_key_of_merged_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    },
    {
      "key": "unique_key_of_deleted_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    }
  ]
}  

Código de status: 207 é retornado quando pelo menos um item não foi indexado com êxito. Os itens que não foram indexados têm o campo de status definido como false. As propriedades errorMessage e statusCode indicarão o motivo do erro de indexação:

{
  "value": [
    {
      "key": "unique_key_of_document_1",
      "status": false,
      "errorMessage": "The search service is too busy to process this document. Please try again later.",
      "statusCode": 503
    },
    {
      "key": "unique_key_of_document_2",
      "status": false,
      "errorMessage": "Document not found.",
      "statusCode": 404
    },
    {
      "key": "unique_key_of_document_3",
      "status": false,
      "errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
      "statusCode": 422
    }
  ]
}  

A propriedade errorMessage indicará o motivo do erro de indexação, se possível.

A tabela a seguir explica os vários códigos de status por documento que podem ser retornados na resposta. Alguns códigos de status indicam problemas com a solicitação em si, enquanto outros indicam condições de erro temporárias. Você deve testar o último novamente após um atraso.

Código de status Significado Permite tentar novamente Observações
200 O documento foi modificado ou excluído com êxito. N/D As operações de exclusão são idempotentes. Ou seja, mesmo se não existir uma chave de documento no índice, a tentativa de uma operação de exclusão com essa chave resultará em um código de status 200.
201 O documento foi criado com êxito. N/D
400 Ocorreu um erro no documento que o impediu de ser indexado. Não A mensagem de erro na resposta indicará o que há de errado com o documento.
404 Não foi possível mesclar o documento porque a chave especificada não existe no índice. Não Esse erro não ocorre em carregamentos, uma vez que eles criam novos documentos e não ocorre em exclusões porque elas são idempotentes.
409 Foi detectado um conflito de versão durante a tentativa de indexar um documento. Sim Isso pode acontecer quando você está tentando indexar o mesmo documento mais de uma vez simultaneamente.
422 O índice está temporariamente indisponível porque ele foi atualizado com o sinalizador 'allowIndexDowntime' definido como 'verdadeiro'. Sim
503 O serviço de pesquisa está temporariamente indisponível, possivelmente devido a uma carga pesada. Sim Neste caso, seu código deverá ser colocado em espera antes de uma nova tentativa, sob o risco de prolongar a indisponibilidade do serviço.

Observação

Se o seu código de cliente com frequência encontrar uma resposta 207, um motivo possível é que o sistema esteja sob carga. Você pode confirmar isso verificando a propriedade statusCode para 503. Se esse for o caso, recomendamos a limitação de solicitações de indexação. Caso contrário, se a indexação de tráfego não diminuir, o sistema poderá começar a rejeitar todas as solicitações com erros 503.

O código de status: 429 indica que você excedeu sua cota no número de documentos por índice. Você deve criar um novo índice ou atualizar para limites de capacidade mais altos.

Exemplos

Exemplo: Upload dois documentos totalmente definidos

{
  "value": [
    {          
      "@search.action": "upload",  
      "HotelId": "1",
      "HotelName": "Secret Point Motel",
      "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
      "Category": "Boutique",
      "Tags": [ "pool", "air conditioning", "concierge" ],
      "ParkingIncluded": false,
      "LastRenovationDate": "1970-01-18T00:00:00Z",
      "Rating": 3.60,
      "Address": {
        "StreetAddress": "677 5th Ave",
        "City": "New York",
        "StateProvince": "NY",
        "PostalCode": "10022",
        "Country": "USA"
      },
      "Location": {
        "type": "Point",
        "coordinates": [ -73.975403, 40.760586 ]
      },
      "Rooms": [
        {
          "Description": "Budget Room, 1 Queen Bed (Cityside)",
          "Description_fr": "Chambre Économique, 1 grand lit (côté ville)",
          "Type": "Budget Room",
          "BaseRate": 96.99,
          "BedOptions": "1 Queen Bed",
          "SleepsCount": 2,
          "SmokingAllowed": true,
          "Tags": [ "vcr/dvd" ]
        },
        {
          "Description": "Budget Room, 1 King Bed (Mountain View)",
          "Description_fr": "Chambre Économique, 1 très grand lit (Mountain View)",
          "Type": "Budget Room",
          "BaseRate": 80.99,
          "BedOptions": "1 King Bed",
          "SleepsCount": 2,
          "SmokingAllowed": true,
          "Tags": [ "vcr/dvd", "jacuzzi tub" ]
        }
      ]  
    },
    {  
      "@search.action": "upload",  
      "HotelId": "2",
      "HotelName": "Twin Dome Motel",
      "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
      "Description_fr": "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
      "Category": "Boutique",
      "Tags": [ "pool", "free wifi", "concierge" ],
      "ParkingIncluded": false,
      "LastRenovationDate": "1979-02-18T00:00:00Z",
      "Rating": 3.60,
      "Address": {
        "StreetAddress": "140 University Town Center Dr",
        "City": "Sarasota",
        "StateProvince": "FL",
        "PostalCode": "34243",
        "Country": "USA"
      },
      "Location": {
        "type": "Point",
        "coordinates": [ -82.452843, 27.384417 ]
      },
      "Rooms": [
        {
          "Description": "Suite, 2 Double Beds (Mountain View)",
          "Description_fr": "Suite, 2 lits doubles (vue sur la montagne)",
          "Type": "Suite",
          "BaseRate": 250.99,
          "BedOptions": "2 Double Beds",
          "SleepsCount": 2,
          "SmokingAllowed": false,
          "Tags": [ "Room Tags" ]
        }
      ]
    }, 
    {  
      "@search.action": "merge",  
      "HotelId": "3",  
      "Rating": 2.39,  
      "Description": "Surprisingly expensive",  
      "LastRenovationDate": null  
    },  
    {  
      "@search.action": "delete",  
      "hotelId": "4"  
    }  
  ]  
}  

Observação

Quando você carrega DateTimeOffset valores com informações de fuso horário em seu índice, Azure Cognitive Search normaliza esses valores para UTC. Por exemplo, 2019-01-13T14:03:00-08:00 será armazenado como 2019-01-13T22:03:00Z. Se você precisar armazenar informações de fuso horário, precisará adicionar uma coluna extra ao índice.

Confira também