Custom Web API skill in an Azure AI Search enrichment pipeline

The Custom Web API skill allows you to extend AI enrichment by calling out to a Web API endpoint providing custom operations. Similar to built-in skills, a Custom Web API skill has inputs and outputs. 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. The response is expected to have the outputs specified by your custom skill. Any other response is considered an error and no enrichments are performed. The structure of the JSON payload is described further down in this document.

The structure of the JSON payload is described further down in this document.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Skill parameters

Parameters are case-sensitive.

Skill inputs

There are no predefined inputs for this skill. The inputs are any existing field, or any node in the enrichment tree that you want to pass to your custom skill.

Skill outputs

There are no predefined outputs for this skill. Be sure to define an output field mapping in the indexer if the skill's output should be sent to a field in the search index.

Sample 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"
    }
  ]
}

Sample input JSON structure

This JSON structure represents the payload that is sent to your Web API. It always follows these constraints:

• The top-level entity is called values and is an array of objects. The number of such objects are at most the batchSize.

• Each object in the values array has:

  • A recordId property that is a unique string, used to identify that record.

  • A data property that is a JSON object. The fields of the data property corresponds to the "names" specified in the inputs section of the skill definition. The values of those fields are 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": []
           }
      }
    ]
}

Sample output JSON structure

The "output" corresponds to the response returned from your Web API. The Web API should only return a JSON payload (verified by looking at the Content-Type response header) and should satisfy the following constraints:

• There should be a top-level entity called values, which should be an array of objects.

• The number of objects in the array should be the same as the number of objects sent to the Web API.

• Each object should have:

  • A recordId property.

  • 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.

  • An errors property, an array listing any errors encountered that is added to the indexer execution history. This property is required, but can have a null value.

  • A warnings property, an array listing any warnings encountered that is added to the indexer execution history. This property is required, but can have a null value.

• The ordering of objects in the values in either the request or response isn't important. However, the recordId is used for correlation so any record in the response containing a recordId, which wasn't part of the original request to the Web API is 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"
              }
            ]
        },
    ]
}

Error cases

In addition to your Web API being unavailable, or sending out non-successful status codes the following are considered erroneous cases:

• If the Web API returns a success status code but the response indicates that it isn't application/json then the response is considered invalid and no enrichments are performed.

• If there are invalid records (for example, recordId is missing or duplicated) in the response values array, no enrichment is performed for the invalid records. It's important to adhere to the Web API skill contract when developing custom skills. You can refer to this example provided in the Power Skill repository that follows the expected contract.

For cases when the Web API is unavailable or returns an HTTP error, a friendly error with any available details about the HTTP error is added to the indexer execution history.

See also

• Define a skillset
• Add custom skill to an AI enrichment pipeline
• Example: Creating a custom skill for AI enrichment
• Power Skill repository