スキルセットの作成または更新 (プレビュー REST API)

[アーティクル]
06/29/2023

適用対象: 2023-07-01-Preview、2021-04-30-Preview

重要

2023-07-01-Preview (変更なし)。

2021-04-30-Preview では、スキルセット関連の接続に対するマネージド ID のサポートが追加されました。

ナレッジストアの下の "storageConnectionString" は、Azure AD 認証用の Azure リソース ID を受け入れます。
"ID" は 、ユーザー割り当てマネージド ID を受け入れます。このプロパティはナレッジストアにあります。また、Azure Key Vaultでカスタマーマネージドキーを取得するための "encryptionKey" の下にもあります。

このプレビュー API では、カスタムスキルからのマネージド ID 接続もサポートされています。詳細については、「カスタム Web API リファレンス」を参照してください。

スキルセットは、AI エンリッチメントに使用されるコグニティブスキルのコレクションであり、Azure Storage に外部ナレッジストアも作成するオプションがあります。スキルは、自然言語処理やその他の機械学習プロセス (エンティティ認識、キーフレーズ抽出、テキストの論理ページへのチャンクなど) を呼び出します。

スキルセットはインデクサーにアタッチされます。スキルセットを使用するには、インデクサーでそれを参照し、インデクサーを実行してデータのインポート、エンリッチメントの呼び出し、インデックスへの出力の送信を行います。スキルセットは高レベルのリソースですが、インデクサー処理内でのみ動作します。大まかなリソースとして、複数のインデクサーで参照できます。

作成要求で 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 で更新することです。

注意

スキルセットは、 AI エンリッチメントの基礎です。無料のリソースは制限された処理に使用できますが、より大規模または頻繁なワークロードの場合は、課金対象の Cognitive Services リソースをアタッチします。

URI パラメーター

パラメーター	説明
サービス名	必須。このプロパティを、検索サービスの一意のユーザー定義名に設定します。
スキルセット名	PUT を使用する場合は、URI で必須です。名前は小文字で、文字または数字で始まり、スラッシュやドットがなく、128 文字未満である必要があります。名前を文字または数字で開始した後、ダッシュが連続していない限り、名前の残りの部分には任意の文字、数字、ダッシュを含めることができます。
api-version	必須。現在のプレビューバージョンはです `2023-07-01-Preview`。その他のバージョンについては、「API のバージョン」を参照してください。
disableCacheReprocessingChangeDetection	省略可能 (`false` 既定)。スキルセットの実行中にシナリオを更新し、キャッシュされたエンリッチメントを使用する場合に適用されます。現在のアクションに基づいて既存のドキュメントが更新されないようにするには、をに `true` 設定します。たとえば、スキルセットを実行せずにスキルセットを更新する場合などです。詳細については、「スキルセットの評価をバイパスする」を参照してください。

要求ヘッダー

次の表では、必須と省略可能の要求ヘッダーについて説明します。

フィールド説明

Content-Type 必須。このプロパティをに設定します。 application/json

api-key Azure ロールを使用していて、要求でベアラートークンが提供されている場合は省略可能。それ以外の場合はキーが必要です。 api-key は、検索サービスに対する要求を認証する一意のシステム生成文字列です。要求の作成には、(クエリキーではなく) 管理者キーに設定されたヘッダーを含める api-key 必要があります。詳細については、「キー認証を使用して Azure AI Search に接続する」を参照してください。

フィールド	説明
Content-Type	必須。このプロパティをに設定します。 `application/json`
api-key	Azure ロールを使用していて、要求でベアラートークンが提供されている場合は省略可能。それ以外の場合はキーが必要です。 api-key は、検索サービスに対する要求を認証する一意のシステム生成文字列です。要求の作成には、(クエリキーではなく) 管理者キーに設定されたヘッダーを含める `api-key` 必要があります。詳細については、「キー認証を使用して Azure AI Search に接続する」を参照してください。

要求本文

要求の本文には、スキルセット定義が含まれています。スキルはスタンドアロンであるか、入力と出力の関連付けを介して連結され、ある変換の出力が別の変換への入力になります。 1 つのスキルセットには、スキルが少なくとも 1 つ必要です。スキルの最大数に理論上の制限はありませんが、3 つから 5 つがよくある構成です。

次の 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、名前、コンテキスト、および入力パラメーターと出力パラメーターがあります。スキルリファレンスについては、概念に関するドキュメントを参照してください。配列には、組み込みのスキルとカスタムスキルを含めることができます。少なくとも 1 つのスキルが必要です。ナレッジストアを使用している場合は、プロジェクション内でデータ図形を定義しない限り、Shaper スキルを含めます。
cognitiveServices	インデクサーごとに毎日 20 を超えるドキュメントでCognitive Services APIsを呼び出す課金対象スキルには、オールインワンキーが必要です。キーは、検索サービスと同じリージョン内のリソース用である必要があります。詳細については、「 Cognitive Services リソースをアタッチする」を参照してください。スキルセットがカスタムスキル、ユーティリティスキル (条件付き、シェーパー、テキストマージ、テキスト分割)、またはドキュメント抽出スキルのみで構成されている場合は、キーとこのセクションを省略できます。カスタムエンティティ参照スキルを使用している場合は、このセクションと、インデクサーごとに毎日 20 トランザクションを超えるトランザクションを有効にするキーを含めます。
knowledgeStore	省略可能。 Azure Storage へのエンリッチメント出力の宛先。 Azure Storage アカウントとプロジェクションへの接続文字列が必要です。
encryptionKey	省略可能。 Azure Key Vaultで管理される独自のキーを使用してスキルセット定義内の機密データを暗号化するために使用されます。詳細については、「Azure Key Vault でのカスタマーマネージドキーを使用した Azure AI Search 暗号化」を参照してください。

Response

要求が成功した場合は、状態コード "201 Created" が表示されます。

既定では、応答本文には作成されたスキルセット定義の JSON が含まれます。ただし、Prefer 要求ヘッダーが return=minimal に設定された場合、応答本文は空になり、成功の状態コードは "201 Created" ではなく "204 No Content" になります。これは、スキルセットを作成するのに PUT または POST のどちらが使用されかに関わらず同じです。

例

例: 顧客レビューでビジネスエンティティとセンチメントを認識するスキルセット

このスキルセットは、2 つの異なる変換として個別に処理 /document/content する 2 つのスキルを非同期的に使用します。スキルはエンティティ認識とセンチメントです。エンリッチメントツリーで、 /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 Storage アカウントへの接続文字列と、エンリッチされたコンテンツが (オブジェクトまたはファイルとして) テーブルまたは BLOB ストレージに格納されるかどうかを決定するプロジェクションが必要です。

プロジェクション (特にテーブルプロジェクション) には、エンリッチメントツリーからノードを入力として収集し、プロジェクションに渡すことができる単一の図形を出力するアップストリーム Shaper スキルが必要です。通常、シェーパーは最後に処理されるスキルです。テーブルプロジェクションでは、シェーパースキルのノードによってテーブル内のフィールドが決定されます。

{
  "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": { }
}

例: マネージド ID を使用した接続

マネージド ID は、ナレッジストアへの接続と、カスタムスキルからの外部コードへの接続で使用できます。この例では、両方のシナリオを示します。ナレッジストアの場合、追加の "id" プロパティは、Azure AD が要求の認証に使用する検索サービスのユーザー割り当てマネージド ID を指定します。 "identity" を省略すると、検索サービスのシステム割り当てマネージド ID が使用されます。 Azure AD で呼び出し元を認証するには、検索サービスをマネージド ID 用に構成する必要があります。 Azure Storage に書き込むには、検索 ID に "ストレージ BLOB データ共同作成者" アクセス許可が必要です。

カスタムスキルでは、カスタムコードをホストする Azure 関数またはアプリに対する認証にマネージド ID を使用できます。これには、マネージド ID を使用して接続が認証されていることを示す "authResourceId" プロパティが含まれています。 "authResourceId" の値は、Microsoft ID プロバイダーによって作成されたアプリケーション ID です。この値は、インデクサーによって取得された認証トークンを検証するために使用され、カスタム Web スキル 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)"}
    }
}

定義

Link	説明
knowledgeStore	ナレッジマイニングとデータ処理のシナリオを使用するために、オブジェクト、ファイル、テーブルの形式で、Azure Storage とプロジェクトのエンリッチされたコンテンツへの接続を構成します。
encryptionKey	カスタマーマネージド暗号化のために Azure Key Vault への接続を構成します。

knowledgeStore

ナレッジストアは、スキルセットと AI エンリッチメントパイプラインを作成したエンリッチされたデータのリポジトリです。これは Azure Storage に存在し、オブジェクト、ファイル、テーブルの形式のデータプロジェクションで構成されます。これは、ナレッジマイニング、Power BI でのデータ探索などの検索以外のシナリオ、または他のアプリによるダウンストリーム処理を行うデータシンクとして使用されます。

Azure Storage への接続は、キーを含むフルアクセス接続文字列か、検索サービスがマネージド ID で実行され、ナレッジストアエンドポイントへの書き込みアクセスを許可する Azure ロールの割り当てがある場合のストレージリソース ID です。

属性説明

storageConnectionString

属性	説明
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]/;"`
identity	省略可能。型の `#Microsoft.Azure.Search.DataUserAssignedIdentity` が`userAssignedIdentity`含まれており、検索サービスのユーザー割り当てマネージド ID を指定します。このプロパティは、ストレージアカウントのリソース ID を指定する接続文字列があることによって異なります`storageConnectionString`。プロパティが `identity` null の場合、リソース ID への接続はシステム管理プロパティを使用して行われます。このプロパティが型 `#Microsoft.Azure.Search.DataNoneIdentity`に割り当てられている場合は、以前に指定されていた明示的な ID がクリアされます。
プロジェクション	必須。、で構成されるプロジェクションの`tablesobjectsfiles`配列。指定または null のいずれかです。

必須。次のいずれかの形式の文字列。

"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]/;"

identity

省略可能。型の #Microsoft.Azure.Search.DataUserAssignedIdentity がuserAssignedIdentity含まれており、検索サービスのユーザー割り当てマネージド ID を指定します。このプロパティは、ストレージアカウントのリソース ID を指定する接続文字列があることによって異なりますstorageConnectionString。

プロパティが identity null の場合、リソース ID への接続はシステム管理プロパティを使用して行われます。

このプロパティが型 #Microsoft.Azure.Search.DataNoneIdentityに割り当てられている場合は、以前に指定されていた明示的な ID がクリアされます。

プロジェクション必須。、で構成されるプロジェクションのtablesobjectsfiles配列。指定または null のいずれかです。

プロジェクション

プロジェクションは、ナレッジストア内のデータ構造の定義です。すべての名前はユーザー定義です。 Azure Storage で関連するコンテンツを識別するのに役立つ名前付け規則を採用できます。

属性説明

テーブル

属性	説明
テーブル	Azure Table Storage の 1 つ以上のテーブルにデータ図形を投影します。各ドキュメントの要素はテーブル内の行に投影されます。各テーブルには、次の 3 つのプロパティを指定できます。まず、 `name` (必須) によって、Azure Table Storage で作成または使用するテーブルが決定されます。次に、 `generatedKeyName` (省略可能) は、ドキュメントを一意に識別する列の名前です。この列の値は、エンリッチメント中に生成されます。これを省略すると、検索サービスによってテーブル名に基づいて既定のキー列が作成されます。 3 つ目は、 `source`プロジェクションの形状を提供するエンリッチメントツリーのノードへのパスです (必須)。通常は Shaper スキルの出力です。パスは、ルートエンリッチメントされたドキュメントを表すで始まり`/document/`、エンリッチメントツリー内の、、または`/document/content/`別のノードに`/document/<shaper-output>/`拡張されます。例: `/document/countries/` (すべての国)、または `/document/countries//states/*` (すべての国のすべての州)。
オブジェクト	ドキュメントを BLOB としてAzure Blob Storageプロジェクトします。各オブジェクトには、2 つの必須プロパティがあります。最初に、は、 `storageContainer` Azure Blob Storageで作成または使用するコンテナーの名前です。 2 つ目は、 `source` プロジェクションの形状を提供するエンリッチメントツリーのノードへのパスです。有効な JSON である必要があります。ノードは、有効な JSON を出力するスキルまたは Shaper スキルの出力から JSON オブジェクトを提供する必要があります。
ファイル	各ファイルエントリは、Blob Storage 内のバイナリイメージのストレージを定義します。ファイルプロジェクションには、2 つの必須プロパティがあります。最初に、は、 `storageContainer` Azure Blob Storageで作成または使用するコンテナーの名前です。 2 つ目は、 `source` プロジェクションのルートであるエンリッチメントツリーのノードへのパスです。このプロパティの有効な値は、 `"/document/normalized_images/*"` Blob Storage から提供されたイメージに対してです。

Azure Table Storage の 1 つ以上のテーブルにデータ図形を投影します。各ドキュメントの要素はテーブル内の行に投影されます。各テーブルには、次の 3 つのプロパティを指定できます。

まず、 name (必須) によって、Azure Table Storage で作成または使用するテーブルが決定されます。

次に、 generatedKeyName (省略可能) は、ドキュメントを一意に識別する列の名前です。この列の値は、エンリッチメント中に生成されます。これを省略すると、検索サービスによってテーブル名に基づいて既定のキー列が作成されます。

3 つ目は、 sourceプロジェクションの形状を提供するエンリッチメントツリーのノードへのパスです (必須)。通常は Shaper スキルの出力です。パスは、ルートエンリッチメントされたドキュメントを表すで始まり/document/、エンリッチメントツリー内の、、または/document/content/別のノードに/document/<shaper-output>/拡張されます。例: /document/countries/* (すべての国)、または /document/countries/*/states/* (すべての国のすべての州)。

オブジェクト

ドキュメントを BLOB としてAzure Blob Storageプロジェクトします。各オブジェクトには、2 つの必須プロパティがあります。

最初に、は、 storageContainer Azure Blob Storageで作成または使用するコンテナーの名前です。

2 つ目は、 source プロジェクションの形状を提供するエンリッチメントツリーのノードへのパスです。有効な JSON である必要があります。ノードは、有効な JSON を出力するスキルまたは Shaper スキルの出力から JSON オブジェクトを提供する必要があります。

ファイル

各ファイルエントリは、Blob Storage 内のバイナリイメージのストレージを定義します。

ファイルプロジェクションには、2 つの必須プロパティがあります。最初に、は、 storageContainer Azure Blob Storageで作成または使用するコンテナーの名前です。

2 つ目は、 source プロジェクションのルートであるエンリッチメントツリーのノードへのパスです。このプロパティの有効な値は、 "/document/normalized_images/*" Blob Storage から提供されたイメージに対してです。

encryptionKey

追加のカスタマーマネージド暗号化キー (CMK) 用に Azure Key Vaultへの接続を構成します。カスタマーマネージドキーを使用した暗号化は、無料サービスでは使用できません。課金対象サービスの場合、2019-01-01 以降に作成された検索サービスでのみ使用できます。

キーコンテナーへの接続を認証する必要があります。この目的には、"accessCredentials" またはマネージド ID のいずれかを使用できます。

マネージド ID は、システムまたはユーザー割り当て (プレビュー) にすることができます。検索サービスにシステム割り当てマネージド ID と、キーコンテナーへの読み取りアクセスを許可するロールの割り当ての両方がある場合は、"identity" と "accessCredentials" の両方を省略でき、要求はマネージド ID を使用して認証されます。検索サービスにユーザー割り当て ID とロールの割り当てがある場合は、"identity" プロパティをその ID のリソース ID に設定します。

属性	説明
keyVaultKeyName	必須。暗号化に使用される Azure Key Vault キーの名前。
keyVaultKeyVersion	必須。 Azure Key Vault キーのバージョン。
keyVaultUri	必須。キーを提供する Azure Key Vaultの URI (DNS 名とも呼ばれます)。 URI の例として、`https://my-keyvault-name.vault.azure.net` があります。
accessCredentials	マネージド ID を使用している場合は省略します。それ以外の場合、の`accessCredentials`プロパティには、(指定した Azure Key Vaultへのアクセス許可を持つ Azure Active Directory アプリケーション ID)、および `applicationSecret` (指定した Azure AD アプリケーションの認証キー) が含まれます`applicationId`。
identity	Azure Key Vault への検索サービス接続にユーザー割り当てマネージド ID を使用している場合を除き、省略可能です。形式は `"/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"` です。