Aptitud API web personalizada en una canalización de enriquecimiento de Azure Cognitive SearchCustom Web API skill in an Azure Cognitive Search enrichment pipeline

La aptitud API web personalizada permite extender el enriquecimiento con IA al llamar a un punto de conexión de la API web que proporciona operaciones personalizadas.The Custom Web API skill allows you to extend AI enrichment by calling out to a Web API endpoint providing custom operations. De manera similar a las aptitudes integradas, una aptitud API web personalizada tiene entradas y salidas.Similar to built-in skills, a Custom Web API skill has inputs and outputs. En función de las entradas, la API web recibe una carga de JSON cuando se ejecuta el indexador y genera una carga de JSON como respuesta, junto con un código de estado correcto.Depending on the inputs, your Web API receives a JSON payload when the indexer runs, and outputs a JSON payload as a response, along with a success status code. Se espera que la respuesta tenga las salidas especificadas por la aptitud personalizada.The response is expected to have the outputs specified by your custom skill. Cualquier otra respuesta se considera un error y no se realiza ningún enriquecimiento.Any other response is considered an error and no enrichments are performed.

La estructura de las cargas JSON se describen con mayor detalle más adelante en este documento.The structure of the JSON payloads are described further down in this document.

Nota

El indizador realizará dos reintentos para ciertos códigos de estado HTTP estándar devueltos desde la API web.The indexer will retry twice for certain standard HTTP status codes returned from the Web API. Estos códigos de estado HTTP son:These HTTP status codes are:

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkillMicrosoft.Skills.Custom.WebApiSkill

Parámetros de la aptitudSkill parameters

Los parámetros distinguen mayúsculas de minúsculas.Parameters are case-sensitive.

Nombre de parámetroParameter name DESCRIPCIÓNDescription
uriuri URI de la API web adonde se enviará la carga de JSON.The URI of the Web API to which the JSON payload will be sent. Solo se permite el esquema de URI httpsOnly https URI scheme is allowed
httpMethodhttpMethod Método que se usará al enviar la carga.The method to use while sending the payload. Los métodos permitidos son PUT o POSTAllowed methods are PUT or POST
httpHeadershttpHeaders Colección de pares clave-valor donde las claves representan los nombres de encabezados y los valores representan los valores de encabezados que se enviarán a la API web junto con la carga.A collection of key-value pairs where the keys represent header names and values represent header values that will be sent to your Web API along with the payload. Estos encabezados no se permiten en esta colección: Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade, ViaThe following headers are prohibited from being in this collection: Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade, Via
timeouttimeout (Opcional) Cuando se especifica, indica el tiempo de expiración del cliente http que hace la llamada API.(Optional) When specified, indicates the timeout for the http client making the API call. Debe tener el formato de un valor "dayTimeDuration" XSD (subconjunto restringido de un valor de duración ISO 8601 ).It must be formatted as an XSD "dayTimeDuration" value (a restricted subset of an ISO 8601 duration value). Por ejemplo, PT60S para 60 segundos.For example, PT60S for 60 seconds. Si no se establece, se elige el valor predeterminado de 30 segundos.If not set, a default value of 30 seconds is chosen. El tiempo de expiración se puede establecer en un máximo de 230 segundos y un mínimo de 1.The timeout can be set to a maximum of 230 seconds and a minimum of 1 second.
batchSizebatchSize (Opcional) Indica cuántos "registros de datos" (consulte la estructura de la carga de JSON que se muestra más adelante) se enviarán por llamada API.(Optional) Indicates how many "data records" (see JSON payload structure below) will be sent per API call. Si no se establece, se elige un valor predeterminado de 1000.If not set, a default of 1000 is chosen. Se recomienda usar este parámetro para lograr un equilibrio adecuado entre el rendimiento de la indexación y la carga en la APIWe recommend that you make use of this parameter to achieve a suitable tradeoff between indexing throughput and load on your API
degreeOfParallelismdegreeOfParallelism (Opcional) Cuando se especifica, indica el número de llamadas que realizará el indexador en paralelo al punto de conexión que ha proporcionado.(Optional) When specified, indicates the number of calls the indexer will make in parallel to the endpoint you have provided. Puede reducir este valor si el punto de conexión no puede con una carga demasiado elevada de solicitudes o aumentarlo si el punto de conexión es capaz de aceptar más solicitudes y desea un aumento en el rendimiento del indexador.You can decrease this value if your endpoint is failing under too high of a request load, or raise it if your endpoint is able to accept more requests and you would like an increase in the performance of the indexer. Si no se establece, se usa un valor predeterminado de 5.If not set, a default value of 5 is used. degreeOfParallelism se puede establecer en un máximo de 10 y un mínimo de 1.The degreeOfParallelism can be set to a maximum of 10 and a minimum of 1.

Entradas de la aptitudSkill inputs

No hay entradas "predefinidas" para esta aptitud.There are no "predefined" inputs for this skill. Puede elegir uno o más campos que ya estarían disponibles en el momento de la ejecución de esta aptitud como entradas y la carga de JSON enviada a la API web tendrá distintos campos.You can choose one or more fields that would be already available at the time of this skill's execution as inputs and the JSON payload sent to the Web API will have different fields.

Salidas de la aptitudSkill outputs

No hay salidas "predefinidas" para esta aptitud.There are no "predefined" outputs for this skill. En función de la respuesta que devuelva la API web, agregue campos de salida para poder seleccionarlos desde la respuesta de JSON.Depending on the response your Web API will return, add output fields so that they can be picked up from the JSON response.

Definición de ejemploSample definition

  {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "description": "A custom skill that can identify positions of different phrases in the source text",
        "uri": "https://contoso.count-things.com",
        "batchSize": 4,
        "context": "/document",
        "inputs": [
          {
            "name": "text",
            "source": "/document/content"
          },
          {
            "name": "language",
            "source": "/document/languageCode"
          },
          {
            "name": "phraseList",
            "source": "/document/keyphrases"
          }
        ],
        "outputs": [
          {
            "name": "hitPositions"
          }
        ]
      }

Estructura de JSON de entrada de ejemploSample input JSON structure

Esta estructura JSON representa la carga que se enviará a la API web.This JSON structure represents the payload that will be sent to your Web API. Siempre seguirá estas restricciones:It will always follow these constraints:

  • La entidad de nivel superior se llama values y será una matriz de objetos.The top-level entity is called values and will be an array of objects. El número de dichos objetos será como máximo el batchSizeThe number of such objects will be at most the batchSize
  • Cada objeto de la matriz values tendráEach object in the values array will have
    • Una propiedad recordId que será una cadena única usada para identificar ese registro.A recordId property that is a unique string, used to identify that record.
    • Una propiedad data que será un objeto JSON.A data property that is a JSON object. Los campos de la propiedad data corresponderán a los "nombres" especificados en la sección inputs de la definición de aptitud.The fields of the data property will correspond to the "names" specified in the inputs section of the skill definition. El valor de esos campos provendrá del source de esos campos (que podrían ser de un campo del documento o posiblemente de otra aptitud).The value of those fields will be from the source of those fields (which could be from a field in the document, or potentially from another skill)
{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Estructura JSON de salida de ejemploSample output JSON structure

La "salida" corresponde a la respuesta devuelta desde la API web.The "output" corresponds to the response returned from your Web API. La API web solo debe devolver una carga de JSON (que se comprueba al mirar el encabezado de la respuesta Content-Type) y debe cumplir con estas restricciones:The Web API should only return a JSON payload (verified by looking at the Content-Type response header) and should satisfy the following constraints:

  • Debe haber una entidad de nivel superior llamada values, que debe ser una matriz de objetos.There should be a top-level entity called values which should be an array of objects.
  • El número de objetos en la matriz debe ser el mismo número de objetos enviados a la API web.The number of objects in the array should be the same as the number of objects sent to the Web API.
  • Cada objeto debe tener:Each object should have:
    • Una propiedad recordIdA recordId property
    • Una propiedad data, que es un objeto donde los campos son enriquecimientos que coinciden con los "nombres" en output y cuyos valores se consideran el enriquecimiento.A data property, which is an object where the fields are enrichments matching the "names" in the output and whose value is considered the enrichment.
    • Una propiedad errors, una matriz que muestra todos los errores detectados que se agregarán al historial de ejecuciones del indizador.An errors property, an array listing any errors encountered that will be added to the indexer execution history. Esta propiedad es obligatoria, pero puede tener un valor null.This property is required, but can have a null value.
    • Una propiedad warnings, una matriz que muestra todas las advertencias detectadas que se agregarán al historial de ejecuciones del indizador.A warnings property, an array listing any warnings encountered that will be added to the indexer execution history. Esta propiedad es obligatoria, pero puede tener un valor null.This property is required, but can have a null value.
  • No es necesario que los objetos de la matriz values estén en el mismo orden que los objetos de la matriz values enviados como solicitud a la API web.The objects in the values array need not be in the same order as the objects in the values array sent as a request to the Web API. Sin embargo, recordId se usa para correlación, por lo que se descartará cualquier registro de la respuesta que contenga un recordId que no fue parte de la solicitud original a la API web.However, the recordId is used for correlation so any record in the response containing a recordId which was not part of the original request to the Web API will be discarded.
{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": {
                "message": "No occurrences of 'Hi' were found in the input text"
            }
        },
    ]
}

Casos de errorError cases

Además de una API web no disponible o del envío de códigos de estado no correcto, los siguientes se consideran como casos con errores:In addition to your Web API being unavailable, or sending out non-successful status codes the following are considered erroneous cases:

  • Si la API web devuelve un código de estado correcto, pero la respuesta indica que no es application/json, la respuesta se considera como no válida y no se realizará ningún enriquecimiento.If the Web API returns a success status code but the response indicates that it is not application/json then the response is considered invalid and no enrichments will be performed.
  • Si hay registros no válidos (con recordId no en la solicitud original o con valores duplicados) en la matriz values de la respuesta, no se realizará ningún enriquecimiento para esos registros.If there are invalid (with recordId not in the original request, or with duplicate values) records in the response values array, no enrichment will be performed for those records.

En los casos en que la API web no está disponible o devuelve un error HTTP, se agregará un error descriptivo con todos los detalles disponibles sobre el error HTTP al historial de ejecución del indizador.For cases when the Web API is unavailable or returns a HTTP error, a friendly error with any available details about the HTTP error will be added to the indexer execution history.

Otras referenciasSee also