Создание или обновление набора навыков (предварительная версия REST API)

Версия API: 2021-04-30-Preview

Важно!

2021-04-30-Preview добавляет поддержку управляемых удостоверений для подключений, связанных с набором навыков:

• StorageConnectionString вхранилище знаний принимает идентификатор ресурса Azure для проверки подлинности Azure AD.
• "identity" принимает управляемое удостоверение, назначаемое пользователем. Это свойство находится в хранилище знаний. Он также находится в разделе encryptionKey для получения ключа, управляемого клиентом, в Azure Key Vault.

Этот API предварительной версии также поддерживает подключение к управляемому удостоверению из пользовательского навыка. Дополнительные сведения см. в справочнике по пользовательскому веб-API .

Набор навыков — это набор когнитивных навыков, используемых для обогащения СИ, с возможностью создания внешнего хранилища знаний в служба хранилища Azure. Навыки вызывают обработку естественного языка и другие процессы машинного обучения, такие как распознавание сущностей, извлечение ключевых фраз, фрагментирование текста на логические страницы, среди прочего.

Набор навыков присоединен к индексатору. Чтобы использовать набор навыков, создайте ссылку на него в индексаторе, а затем запустите индексатор для импорта данных, вызова обогащения и отправки выходных данных в индекс. Набор навыков — это высокоуровневый ресурс, но он работает только в процессе обработки индексатора. Как высокоуровневый ресурс можно ссылаться на него несколькими индексаторами.

Вы можете использовать POST или PUT в запросе на создание. Для любого из них текст запроса предоставляет определение объекта.

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

Для запросов на обновление используйте PUT и укажите имя набора навыков в URI.

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

Все запросы к службе отправляются по протоколу HTTPS.

Создание набора навыков добавляет его в службу поиска.

Обновление набора навыков полностью перезаписывает существующий набор навыков с содержимым полезных данных запроса. Для обновлений рекомендуется получить определение набора навыков с помощью GET, изменить его, а затем обновить с помощью PUT.

Примечание

Наборы навыков являются основой обогащения ИИ. Бесплатный ресурс доступен для ограниченной обработки, но для больших или более частых рабочих нагрузок присоединяется оплачиваемый ресурс Cognitive Services.

Параметры URI

Параметр	Описание
имя службы	Обязательный. Присвойте этому свойству уникальное, определяемое пользователем имя службы поиска.
Имя набора навыков	Обязательный для универсального кода ресурса (URI) при использовании PUT. Имя должно быть строчным, начинаться с буквы или цифры, не иметь косой черты или точек и быть менее 128 символов. После запуска имени с буквой или цифрой остальная часть имени может включать любые буквы, цифры и дефисы, если дефисы не являются последовательными.
api-version	Обязательный. Текущая стабильная версия api-version=2020-06-30. Дополнительные версии API см. в разделе " Версии API ".
disableCacheReprocessingChangeDetection	Необязательный (false по умолчанию). Применяется к сценариям обновления и использованию кэшированных обогащений во время выполнения набора навыков. Установите для true предотвращения обновлений существующих документов на основе текущего действия, например, если вы хотите обновить набор навыков без запуска набора навыков. Дополнительные сведения см. в разделе об оценке набора навыков обхода.

Заголовки запросов

Таблица ниже содержит обязательные и необязательные заголовки запроса.

Поля	Описание
Content-Type	Обязательный элемент. Задайте для этого свойства значение application/json
api-key	Обязательный. Заголовок api-key используется для проверки подлинности запроса в службе поиска. Это уникальное строковое значение, присваиваемое службе. Запросы на создание должны содержать заголовок, заданный api-key для ключа администратора (в отличие от ключа запроса). Ключ API можно найти на панели мониторинга службы поиска в портал Azure.

Текст запроса

Текст запроса содержит определение набора навыков. Навыки либо изолированы, либо связаны друг с другом посредством связей входных и выходных данных, где выходные данные одного преобразования становятся входными данными в другой. В наборе навыков должен быть хотя бы один навык. Теоретическое ограничение на максимальное число навыков отсутствует, однако типичная конфигурация содержит от трех до пяти навыков.

Следующий код JSON представляет собой высокоуровневое представление основных частей определения.

{   
  "name" : (optional on PUT; required on POST) "Name of the skillset",  
  "description" : (optional) "Anything you want, or nothing at all",   
  "skills" : (required) ["An array of skills. Each skill has an odata.type, name, input and output parameters"],
  "cognitiveServices": 
      {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "Optional. Anything you want, or null",
        "key": "<YOUR-COGNITIVE-SERVICES-ALL-IN-ONE-KEY>"
      },
  "knowledgeStore": (optional) { ... },
  "encryptionKey": (optional) { }
} 

Запрос содержит следующие свойства.

Свойство	Описание
name	Обязательный. Имя набора навыков. Имя должно быть строчным, начинаться с буквы или цифры, не иметь косой черты или точек и быть менее 128 символов. После запуска имени с буквой или цифрой остальная часть имени может включать любые буквы, цифры и дефисы, если дефисы не являются последовательными.
навыки	Массив навыков. Каждый навык имеет параметры odata.type, name, context и input и output. Справочник по навыкам можно найти в концептуальной документации. Массив может включать встроенные навыки и пользовательские навыки. Требуется по крайней мере один навык. Если вы используете хранилище знаний, включите навык фигуры , если вы не определяете фигуру данных в проекции.
cognitiveServices	Для оплачиваемых навыков, которые вызывают API-интерфейсы Cognitive Services более чем на 20 документов ежедневно, на индексатор требуется все ключи. Ключ должен быть для ресурса в том же регионе, что и служба поиска. Дополнительные сведения см. в разделе "Присоединение ресурса Cognitive Services". Этот раздел можно пропустить, если набор навыков состоит только из пользовательских навыков, служебных навыков (условные, фигуры, слияние текста, разделение текста) или навык извлечения документов. Если вы используете навык поиска пользовательских сущностей , включите этот раздел и ключ для включения транзакций, превышающих 20 транзакций ежедневно на индексатор.
knowledgeStore	Необязательный элемент. Назначение для вывода обогащения в служба хранилища Azure. Требуется строка подключения к учетной записи и проекциям служба хранилища Azure.
encryptionKey	Необязательный элемент. Используется для шифрования конфиденциальных данных в определении набора навыков с помощью собственных ключей, управляемых в Key Vault Azure. Дополнительные сведения см. в статье Когнитивный поиск Azure шифровании с помощью ключей, управляемых клиентом, в Azure Key Vault.

Ответ

При успешном выполнении запроса возвращается код состояния 201 (создан).

По умолчанию текст ответа содержит объект JSON для созданного определения набора данных. Однако если заголовок запроса Prefer содержит значение return=minimal, текст ответа будет пустым, а код состояния вместо значения "201 — создан" принимает значение "204 — нет содержимого". При этом не играет роли, какой запрос (PUT или POST) используется для создания набора навыков.

Примеры

Пример. Набор навыков, который распознает бизнес-сущности и тональность в отзывах клиентов

Этот набор навыков использует два навыка асинхронно, независимо от обработки /document/content в качестве двух различных преобразований. Навыки — распознавание сущностей и тональность. В дереве /document/content обогащения предоставляет содержимое (или отзывы клиентов) из внешнего источника данных.

{
  "name": "reviews-ss",
  "description": 
  "Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
  "skills":
  [
    {
      "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
      "context": "/document/content",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "companyName"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
      "inputs": [
           {
              "name": "text",
              "source": "/document/content"
           },
          {
               "name": "languageCode",
               "source": "/document/languageCode"
           }
        ],
      "outputs": [
        {
            "name": "sentiment",
            "targetName": "reviewSentiment"
        },
        {
            "name": "confidenceScores",
            "targetName": "sentimentScore"
        }
      ]
    }
  ],
  "cognitiveServices": 
    {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "description": "mycogsvcs resource in West US 2",
    "key": "<your cognitive services all-in-one key goes here>"
    },
  "knowledgeStore": { },
  "encryptionKey": { }
}

Пример. Хранилище знаний с полным доступом строка подключения и фигурными входными данными

Для хранилища знаний требуется строка подключения в учетную запись служба хранилища Azure и проекции, которые определяют, помещает ли обогащенное содержимое в хранилище таблиц или BLOB-объектов (как объекты или файлы).

Проекциям, особенно табличным проекциям, требуется навык вышестоящего фигурного элемента , который собирает узлы из дерева обогащения в качестве входных данных, выводя одну фигуру, которую можно передать в проекцию. Фигура обычно является последним навыком для обработки. В проекции таблицы узлы в навыке фигуры определяют поля в таблице.

{
  "name": "reviews-ss",
  "description": 
  "Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
  "skills":
  [
    { ... },
    { ... },
    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "context": "/document/content",
      "inputs": [
        {
            "name": "Company",
            "source": "/document/content/companyName"
        },
        {
            "name": "Sentiment_Score",
            "source": "/document/content/sentimentScore"
        },
        {
            "name": "Sentiment_Label",
            "source": "/document/content/reviewSentiment"
        }
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "shapeCustomerReviews"
        }
      ]
    }
  ],
  "cognitiveServices": 
    {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "description": "mycogsvcs resource in West US 2",
    "key": "<your cognitive services all-in-one key goes here>"
    },
  "knowledgeStore": { 
      "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<storage-account-name>;AccountKey=<storage-account-key>;EndpointSuffix=core.windows.net;", 
      "projections": [ 
          { 
            "tables": [ 
                { "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
                . . .
            ], 
            "objects": [ ], 
            "files": [ ]  
          }
      ]     
  } 
  "encryptionKey": { }
}

Пример. Подключения с помощью управляемого удостоверения

Управляемые удостоверения можно использовать для подключений к хранилищу знаний и внешнему коду из пользовательского навыка. В этом примере показаны оба сценария. Для хранилища знаний дополнительное свойство identity указывает управляемое удостоверение, назначаемое пользователем службы поиска, которое Azure AD используется для проверки подлинности запроса. Если не указано "identity", используется управляемое удостоверение службы поиска, назначаемое системой. Чтобы Azure AD для проверки подлинности вызывающего объекта, служба поиска должна быть настроена для управляемого удостоверения. Удостоверение поиска должно иметь разрешения "служба хранилища участник данных BLOB-объектов" для записи в служба хранилища Azure.

Пользовательский навык может использовать управляемое удостоверение для проверки подлинности в функции Azure или приложении, в котором размещен пользовательский код. Он включает свойство authResourceId, указывающее, что подключение проходит проверку подлинности с помощью управляемого удостоверения. Значение authResourceId — это идентификатор приложения, созданный поставщиком удостоверений Майкрософт. Это значение будет использоваться для проверки маркера проверки подлинности, полученного индексатором, и отправляется вместе с пользовательским запросом API веб-навыка.

{
  "name": "reviews-ss",
  "description": "A short description",
  "skills":
  [
    { ... },
    { ... },
    {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "sampleCustomSkill",
        "description": "A custom skill that requests an access token for the application ID specified in authResourceID",
        "context": "/document",
        "uri": "https://[your-app-name].azurewebsites.net/api/EntitySearch",
        "authResourceId": "api://xyz*****-****-****-****-********9876",
        "batchSize": 4,
        "degreeOfParallelism": null,
        "inputs": [
          {
            "name": "text",
            "source": "/document/content"
          },
          {
            "name": "language",
            "source": "/document/languageCode"
          },
          {
            "name": "phraseList",
            "source": "/document/keyphrases"
          }
        ],
        "outputs": [
          {
            "name": "<customSkillOutput>"
          }
        ]
      }
    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "context": "/document/content",
      "inputs": [ ... ],
      "outputs": [ ...]
    }
  ],
  "cognitiveServices": { ... },
  "knowledgeStore": { 
      "storageConnectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;",
      "identity": {
          "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
          "userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]",
      "projections": [ 
          { 
            "tables": [ ], 
            "objects": [ ], 
            "files": [ ]  
          }
      ]     
  }
  "encryptionKey": { }
}

Пример. Ключи шифрования

Ключи шифрования — это ключи, управляемые клиентом, используемые для дополнительного шифрования конфиденциального содержимого. В этом примере показано, как указать шифрование, управляемое клиентом, в наборе навыков.

{
    "name": "reviews-ss",
    "description": "A brief description of the skillset",
    "skills":  [ omitted for brevity ],
    "cognitiveServices": { omitted for brevity },
    "knowledgeStore":  { omitted for brevity  },
    "encryptionKey": (optional) { 
        "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
        "keyVaultKeyVersion": "Version of the Azure Key Vault key",
        "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
        "accessCredentials": (optional, only if not using managed system identity) {
            "applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
            "applicationSecret": "Authentication key of the specified Azure AD application)"}
    }
}

Определения

Ссылка	Описание
knowledgeStore	Настраивает подключение к служба хранилища Azure и проектам обогащенного содержимого в виде объектов, файлов и таблиц для использования сценариев интеллектуального анализа знаний и обработки данных.
encryptionKey	Настраивает подключение к Azure Key Vault для шифрования, управляемого клиентом.

knowledgeStore

Хранилище знаний — это репозиторий обогащенных данных, созданных набором навыков и конвейером обогащения ИИ. Он находится в служба хранилища Azure и состоит из проекций данных в виде объектов, файлов и таблиц. Он используется для сценариев, не относящихся к поиску, таких как интеллектуальный анализ знаний, исследование данных в Power BI или в качестве приемника данных для более последующей обработки другими приложениями.

Подключение к служба хранилища Azure — это либо полный доступ, строка подключения который включает ключ, либо идентификатор ресурса хранилища, предоставленный этой службой поиска, выполняется под управляемым удостоверением и имеет назначение роли Azure, предоставляющее доступ на запись к конечной точке хранилища знаний.

Атрибут	Описание
storageConnectionString	Обязательный элемент. Строка в одном из следующих форматов: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net" "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
удостоверение	Необязательный элемент. Он содержит userAssignedIdentity тип #Microsoft.Azure.Search.DataUserAssignedIdentity и указывает назначаемое пользователем управляемое удостоверение службы поиска. Это свойство зависит от наличия storageConnectionString строка подключения, указывающего идентификатор ресурса учетной записи хранения. identity Если свойство имеет значение NULL, подключение к идентификатору ресурса выполняется с помощью управляемого системой свойства. Если этому свойству присваивается тип #Microsoft.Azure.Search.DataNoneIdentity, удаляется любое явное удостоверение, которое было указано ранее.
projections	Обязательный. Массив проекций, состоящих из tables, objectsfilesкоторые являются указанными или пустыми.

Проекции

Проекции — это определения структур данных в хранилище знаний. Все имена определяются пользователем. Вы можете применить соглашение об именовании, которое помогает определить связанное содержимое в служба хранилища Azure.

Атрибут	Описание
В таблицах	Проекты фигур данных в одну или несколько таблиц в таблице Azure служба хранилища, где элементы из каждого документа проецируются в строки таблицы. Каждая таблица может иметь следующие три свойства. Во-первых, name (обязательно) определяет таблицу для создания или использования в таблице Azure служба хранилища. Во-вторых, generatedKeyName (необязательно) — это имя столбца, однозначно определяющего документ. Значения для этого столбца будут создаваться во время обогащения. Если опустить его, служба поиска создаст ключевой столбец по умолчанию на основе имени таблицы. В-третьих, source (обязательно) — это путь к узлу дерева обогащения, который предоставляет форму проекции. Обычно это выходные данные навыка фигуры. Пути начинаются с /document/, представляющих корневой обогащенный документ, а затем расширяются до /document/<shaper-output>/или /document/content/другого узла в дереве обогащения. Примеры: /document/countries/* (все страны) или /document/countries/*/states/* (все государства во всех странах).
объекты	Проекты документов в виде больших двоичных объектов в Хранилище BLOB-объектов Azure. Каждый объект имеет два обязательных свойства. Во-первых, storageContainer это имя контейнера для создания или использования в Хранилище BLOB-объектов Azure. Во-вторых, source это путь к узлу дерева обогащения, который предоставляет форму проекции. Он должен быть допустимым JSON. Узел должен предоставить объект JSON либо из навыка, который выдает допустимый JSON, либо выходные данные навыка фигуры.
файлы	Каждая запись файла определяет хранилище двоичных образов в служба хранилища BLOB-объектов. Проекции файлов имеют два обязательных свойства. Во-первых, storageContainer это имя контейнера для создания или использования в Хранилище BLOB-объектов Azure. Во-вторых, source это путь к узлу дерева обогащения, который является корнем проекции. Допустимое значение этого свойства предназначено "/document/normalized_images/*" для изображений, которые были созданы из служба хранилища BLOB-объектов.

encryptionKey

Настраивает подключение к Azure Key Vault для дополнительных ключей шифрования, управляемых клиентом (CMK). Шифрование с помощью ключей, управляемых клиентом, недоступно для бесплатных служб. Для оплачиваемых служб она доступна только для служб поиска, созданных в 2019-01-01 или после 2019.01.

Подключение к хранилищу ключей должно пройти проверку подлинности. Для этой цели можно использовать accessCredentials или управляемое удостоверение.

Управляемые удостоверения могут быть назначены системой или пользователем (предварительная версия). Если служба поиска имеет управляемое удостоверение, назначаемое системой, и назначение ролей, которое предоставляет доступ на чтение к хранилищу ключей, можно опустить идентификатор и accessCredentials, а запрос будет проходить проверку подлинности с помощью управляемого удостоверения. Если служба поиска имеет назначаемое пользователем удостоверение и назначение ролей, задайте для свойства identity идентификатор ресурса этого удостоверения.

Атрибут	Описание
keyVaultKeyName	Обязательный элемент. Имя ключа Azure Key Vault, используемого для шифрования.
keyVaultKeyVersion	Обязательный. Версия ключа Key Vault Azure.
keyVaultUri	Обязательный. URI Azure Key Vault, который также называется DNS-именем, предоставляющим ключ. Пример URI: https://my-keyvault-name.vault.azure.net.
accessCredentials	Опустить, если вы используете управляемое удостоверение. В противном случае свойства accessCredentials include applicationId (идентификатор приложения Azure Active Directory с разрешениями на доступ к указанному Key Vault Azure) и applicationSecret (ключ проверки подлинности указанного приложения Azure AD).
удостоверение	Необязательный, если вы не используете управляемое удостоверение, назначаемое пользователем, для подключения службы поиска к Azure Key Vault. Формат — "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

См. также раздел

• Определение набора навыков
• Общие сведения об обогащении с помощью ИИ
• Обзор набора навыков
• Обзор хранилища знаний
• Обзор проекции
• Руководство. Использование REST и ИИ для создания контента, допускаемого для поиска, из больших двоичных объектов
• Встроенные навыки