Adición, actualización o eliminación de documentos (API REST de Azure AI Search)
Puede importar documentos de búsqueda en un índice especificado mediante HTTP POST. Para una actualización grande, se recomienda el procesamiento por lotes (hasta 1000 documentos por lote o aproximadamente 16 MB por lote) y mejorará significativamente el rendimiento de la indexación.
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 orígenes de datos de Azure compatibles, los indexadores ofrecen una alternativa más sencilla para agregar y actualizar documentos. Para más información, consulte Indexer operations(Operaciones del indexador).
Parámetros de identificador URI
| Parámetro | Descripción |
|---|---|
| nombre del servicio | Necesario. Establézcalo en el nombre único definido por el usuario del servicio de búsqueda. |
| nombre de índice | Obligatorio en el URI, especificando qué índice se va a publicar en los documentos. Solo se pueden publicar documentos en un índice de cada vez. |
| api-version | Necesario. La versión estable actual es api-version=2020-06-30. Consulte Versiones de API para obtener más versiones. |
Encabezados de solicitud
En la siguiente tabla se describen los encabezados de solicitud obligatorios y opcionales.
| Campos | Descripción |
|---|---|
| Content-Type | Necesario. Establézcalo en application/json |
| api-key | Opcional si usa roles de Azure y se proporciona un token de portador en la solicitud; de lo contrario, se requiere una clave. Una clave de API es una cadena única generada por el sistema que autentica la solicitud en el servicio de búsqueda. La carga de documentos requiere una clave de API de administración. Consulte Conexión a Azure AI Search mediante la autenticación de claves para más información. |
Cuerpo de la solicitud
El cuerpo de la solicitud contiene uno o más documentos para indexar. Los documentos se identifican mediante una clave única que distingue mayúsculas de minúsculas. Cada documento está asociado a una acción: "upload", "delete", "merge" o "mergeOrUpload". Las solicitudes de carga deben incluir los datos del documento como un conjunto de pares de clave/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)
...
},
...
]
}
| Propiedad | Descripción |
|---|---|
| @search.action | Necesario. Los valores válidos son "upload", "delete", "merge" o "mergeOrUpload". El valor predeterminado es "upload". Puede combinar acciones, una por documento, en el mismo lote.
"cargar": una acción de carga es similar a una "upsert" donde se insertará el documento si es nueva y actualizada o reemplazada si existe. Todos los campos se reemplazan en el caso de actualización. "delete": Delete quita el documento especificado del índice. Se omitirá cualquier campo que especifique en una operación de eliminación, que no sea el campo de clave. Si desea quitar un campo individual de un documento, use merge en su lugar y establezca el campo explícitamente en null.
"mergeOrUpload": esta acción se comporta como combinar si ya existe un documento con la clave especificada en el índice. Si el documento no existe, se comporta como cargar con un nuevo documento. "merge": la combinación actualiza un documento existente con los campos especificados. Si el documento no existe, se produce un error en la combinación. Cualquier campo que se especifica en una combinación reemplazará al campo existente en el documento. Esto también se aplica a colecciones de tipos primitivos y complejos. En colecciones primitivas, si el documento contiene un campo Tags de tipo Collection(Edm.String) con un valor de ["budget"], y ejecuta una combinación con un valor de ["economy", "pool"] para Tag, el valor final del campo Tags será ["economy", "pool"]. No será ["budget", "economy", "pool"]. En colecciones complejas, si el documento contiene un campo de colección complejo denominado Rooms con un valor de [{ "Type": "Budget Room", "BaseRate": 75.0 }], y ejecuta una combinación con un valor de [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], el valor final del campo Rooms será [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. No será ninguno de los siguientes: [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (append elements) [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (merge elements in order, then append any extras) |
| key_field_name | Necesario. Definición de campo en el índice que actúa como clave de documento y solo contiene valores únicos. Las claves de documento solo pueden contener letras, números, guiones ("-"), caracteres de subrayado ("_") e signos iguales ("=") y distinguen mayúsculas de minúsculas. Para obtener más información, vea Reglas de nomenclatura. |
| field_name | Necesario. Pares nombre-valor, donde el nombre del campo corresponde a un nombre de campo en la definición del índice. El valor está definido por el usuario, pero debe ser válido para el tipo de campo. |
Nota
No hay garantías de ordenación para las que se ejecuta primero la acción en el cuerpo de la solicitud. No se recomienda tener varias acciones de "combinación" asociadas al mismo documento en un único cuerpo de solicitud. Si hay varias acciones de "combinación" necesarias para el mismo documento, realice la combinación del lado cliente antes de actualizar el documento en el índice de búsqueda.
Response
Código de estado: 200 se devuelve para una respuesta correcta, lo que significa que todos los elementos se han almacenado de forma duradera y comenzarán a indizarse. La indexación se ejecuta en segundo plano y hace que los nuevos documentos estén disponibles (es decir, consultables y buscables) unos segundos después de que se complete la operación de indexación. El retraso específico depende de la carga del servicio.
La indexación correcta se indica mediante la propiedad status que se establece en true para todos los elementos, así como la propiedad statusCode que se establece en 201 (para documentos recién cargados) o 200 (para documentos combinados o eliminados):
{
"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 estado: 207 se devuelve cuando al menos un elemento no se indizara correctamente. Los elementos que no se han indexado tienen el campo de estado establecido en false. Las propiedades errorMessage y statusCode indican el motivo del error de indexación:
{
"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
}
]
}
La propiedad errorMessage indica el motivo del error de indexación si es posible.
En la tabla siguiente se explican los distintos códigos de estado por documento que se pueden devolver en la respuesta. Algunos códigos de estado indican problemas con la propia solicitud, mientras que otros indican condiciones de error temporales. En este último caso debe volver a intentarlo después de un tiempo.
| status code | Significado | Admite reintentos | Notas |
|---|---|---|---|
| 200 | Documento correctamente modificado o eliminado. | N/D | Las operaciones de eliminación son idempotentes. Es decir, incluso si no existe una clave de documento en el índice, si se intenta realizar una operación de eliminación con esa clave, se genera un código de estado 200. |
| 201 | El documento se creó correctamente. | N/D | |
| 400 | Se produjo un error en el documento que ha impedido que se indexe. | No | El mensaje de error de la respuesta indica lo que está mal con el documento. |
| 404 | No se pudo combinar el documento porque la clave especificada no existe en el índice. | No | Este error no se produce para las cargas, ya que crean documentos nuevos y no se produce para las eliminaciones porque son idempotentes. |
| 409 | Se detectó un conflicto de versión al intentar indexar un documento. | Sí | Esto puede ocurrir si intenta indexar el mismo documento más de una vez al mismo tiempo. |
| 422 | El índice no está disponible temporalmente porque se ha actualizado con el indicador 'allowIndexDowntime' establecido en 'true'. | Sí | |
| 503 | El servicio de búsqueda no está disponible temporalmente, posiblemente debido a una carga elevada. | Sí | En este caso, el código debe esperar antes de reintentar ya que, de lo contrario, se arriesga a prolongar la no disponibilidad del servicio. |
Nota
Si el código de cliente encuentra con frecuencia una respuesta 207, una razón posible es que el sistema está bajo carga. Puede confirmar esto comprobando la propiedad statusCode para 503. Si este es el caso, se recomienda la limitación de peticiones de indización. De lo contrario, si el tráfico de indexación de tráfico no se reduce, es posible que el sistema comience a rechazar todas las solicitudes mediante errores 503.
Código de estado: 429 indica que se ha superado la cuota del número de documentos por índice. Debe crear un nuevo índice o actualizar para obtener límites de capacidad superiores.
Ejemplos
Ejemplo: Carga de dos 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"
}
]
}
Nota
Al cargar DateTimeOffset valores con información de zona horaria en el índice, Azure AI Search normaliza estos valores a UTC. Por ejemplo, 2019-01-13T14:03:00-08:00 se almacenará como 2019-01-13T22:03:00Z. Si necesita almacenar información de zona horaria, deberá agregar una columna adicional al índice.