Agregar, actualizar o eliminar documentos (API REST de versión preliminar)
se aplica a: 2023-07-01-Preview. Esta versión ya no se admite. Actualizar inmediatamente a una versión más reciente.
Importante
2023-07-01-Preview agrega:
- Compatibilidad con campos vectoriales en un documento.
Puede insertar documentos que contengan campos vectoriales en un índice especificado mediante HTTP POST. Para una actualización grande, el procesamiento por lotes (hasta 1000 documentos por lote o aproximadamente 16 MB por lote) mejora el rendimiento de la indexación.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2023-07-01-Preview
Content-Type: application/json
api-key: [admin key]
Parámetros de URI
| Parámetro | Descripción |
|---|---|
| nombre del servicio | Obligatorio. Establezca este valor en el nombre único definido por el usuario del servicio de búsqueda. |
| nombre de índice | Obligatorio. Establezca este valor en el nombre del índice que recibe los documentos. Solo puede publicar documentos en un índice cada vez. |
| api-version | Consulte versiones de API para obtener más versiones. |
Encabezados de solicitud
En la tabla siguiente se describen los encabezados de solicitud obligatorios y opcionales.
| Campos | Descripción |
|---|---|
| Tipo de contenido | Obligatorio. Establezca este valor 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 varios documentos que se van a indexar. Los documentos se identifican de forma única mediante una clave 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 clave-valor.
Los campos vectoriales son de tipo Collection(Edm.Single). Los datos vectoriales constan de una matriz de números de punto flotante de precisión sencilla.
Los campos vectoriales pueden contener miles de incrustaciones, dependiendo de la complejidad, longitud o tipo del contenido original. Azure AI Search no convierte contenido en incrustaciones. Los documentos que inserte en un índice deben contener inserciones que haya generado anteriormente.
{
"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),
"vector_field_name": [ array of single-precision floating point numbers ]
...
},
...
]
}
| Propiedad | Descripción |
|---|---|
| @search.action | Obligatorio. Los valores válidos son "upload", "delete", "merge" o "mergeOrUpload". El valor predeterminado es "upload". |
| key_field_name | Obligatorio. Definición de campo en el índice que actúa como clave de documento y contiene solo valores únicos. Las claves de documento solo pueden contener letras, números, guiones ("-"), caracteres de subrayado ("_") y signos iguales ("=") y distinguen mayúsculas de minúsculas. |
| field_name | Obligatorio. Pares nombre-valor, donde el nombre del campo corresponde a un nombre de campo en la definición de índice. El valor está definido por el usuario, pero debe ser válido para el tipo de campo. |
Respuesta
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 que la indexación ha comenzado. 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.
La indexación correcta se indica cuando la propiedad status establecida en true para todos los elementos. La propiedad statusCode debe ser 201 (para documentos recién cargados) o 200 (para documentos combinados o eliminados).
Ejemplos
Ejemplo: Carga de dos documentos con contenido de texto y vector
Para mejorar la legibilidad, en el ejemplo siguiente se muestra un subconjunto de documentos e incrustaciones. El cuerpo de la solicitud Cargar documentos consta de 108 documentos, cada uno con un conjunto completo de incrustaciones para "titleVector" y "contentVector".
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
"value": [
{
"id": "1",
"title": "Azure App Service",
"content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
"category": "Web",
"titleVector": [
-0.02250031754374504,
. . .
],
"contentVector": [
-0.024740582332015038,
. . .
],
"@search.action": "upload"
},
{
"id": "2",
"title": "Azure Functions",
"content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
"category": "Compute",
"titleVector": [
-0.020159931853413582,
. . .
],
"contentVector": [
-0.02780858241021633,,
. . .
],
"@search.action": "upload"
}
. . .
]
}
Nota
Al cargar valores DateTimeOffset 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, agregue una columna adicional al índice.