Update Skillset (Azure AI Search REST API)

Article
09/17/2024

Important

This API reference is for a legacy version. See Data plane REST operations for updated reference documentation. Use the filter on the top left to select a version.

You can update an existing skillset and knowledge store using an HTTP PUT, specifying the name of the skillset to update on the request URI.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
  Content-Type: application/json
  api-key: [admin key]

Note

Skillsets are the basis of AI enrichment in Azure AI Search. A free resource is available for limited processing, but for larger and more frequent workloads, a billable Cognitive Services resource is required. For more information, see Attach a Cognitive Services resource to an Azure AI Search skillset.

URI Parameters

Parameter	Description
service name	Required. Set this to the unique, user-defined name of your search service.
skillset name	Required. The request URI specifies the name of the skillset to update.
api-version	Required. The current stable version is `api-version=2020-06-30`. See API versions for more versions.
disableCacheReprocessingChangeDetection	Optional. Used for incremental enrichment (`false` by default). Set to `true` to prevent updates to existing documents based on the current action. For more information, see cache management.

Request Headers

The following table describes the required and optional request headers.

Fields	Description
Content-Type	Required. Set this to `application/json`
api-key	Optional if you're using Azure roles and a bearer token is provided on the request, otherwise a key is required. An api-key is a unique, system-generated string that authenticates the request to your search service. Update requests must include an `api-key` header set to your admin key (as opposed to a query key). See Connect to Azure AI Search using key authentication for details.

Request Body

The request body syntax is the same as for Create Skillset.

When updating an existing skillset, the entire definition is replaced with the contents of the request body. In general, the best pattern to use for updates is to retrieve the skillset definition with a GET, modify it, and then update it with PUT.

Response

For a successful request, you should see status code "201 Created".

By default, the response body will contain the JSON for the skillset definition that was created. However, if the Prefer request header is set to return=minimal, the response body will be empty, and the success status code will be "204 No Content" instead of "201 Created". This is true regardless of whether PUT or POST is used to create the skillset.

Examples

Example: Update a skillset

The following example updates a skillset used for enriching a collection of financial documents.

PUT https://[servicename].search.windows.net/skillsets/financedocenricher?api-version=2020-06-30
api-key: [admin key]
Content-Type: application/json

The body of request is a JSON document. This particular skillset uses two skills asynchronously, independently processing the substance of /document/content as two different transformations. Alternatively, you can direct the output of one transformation to be the input of another. For more information, see How to define a skillset.

{
  "name": "financedocenricher",
  "description": 
  "An updated version of a skillset used to extract sentiment from financial records, extract company names, and then find additional information about each company mentioned. This version changes the target names.",
  "skills":
  [
    {
      "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "companies"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.SentimentSkill",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "score",
          "targetName": "positivityscore"
        }
      ]
    },
  ],
  "cognitiveServices": 
  {
  "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
  "description": "mycogsvcs resource in West US 2",
  "key": "<your key goes here>"
  }
}

Example: Remove Cognitive Services key

If you would like to update an existing skillset and remove the Cognitive services key attached to it, then modify the cognitiveServices section by setting the @odata.type to #Microsoft.Azure.Search.DefaultCognitiveServices.

{
  "name": "financedocenricher"
  "skills":
  [
    {
      "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "companies"
        }
      ]
    },
  ],
  "cognitiveServices": 
  {
  "@odata.type": "#Microsoft.Azure.Search.DefaultCognitiveServices"
  }
}

Share via