インデクサーの作成 (Azure AI Search REST API)

インデクサーは、Azure Storage、Azure SQL Database、Azure Cosmos DB などのサポートされている Azure データ ソースからのインデックス作成を自動化して、いくつかの名前を付けます。 インデクサーは、定義済みの データ ソース と インデックス を使用して、ソース データを抽出してシリアル化し、データ インジェストのために検索サービスに渡すインデックス作成パイプラインを確立します。 画像と非構造化テキストの AI エンリッチメントの場合、インデクサーは AI 処理を定義する スキルセット を受け入れることもできます。

インデクサーを作成すると、検索サービスに追加されて実行されます。 要求が成功すると、インデックスにデータ ソースからの検索可能なコンテンツが設定されます。

要求に対して POST または PUT を使用できます。 いずれの場合も、要求本文の JSON ドキュメントによってオブジェクト定義が提供されます。

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

または、PUT を使用して、URI にインデクサー名を指定することもできます。

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

HTTPS はすべてのサービス要求に必要です。 インデクサーが存在しない場合は、作成されます。 既に存在する場合は、新しい定義に更新されますが、インデクサーの実行が必要な場合 は、インデクサーの実行 要求を発行する必要があります。

インデクサーの構成は、データ ソースの種類によって異なります。 インデクサーの作成に関するデータ プラットフォーム固有のガイダンスについては、「インデクサーの概要」から始めてください。そこに、関連記事の完全な一覧が記載されています。

URI パラメーター

要求ヘッダー

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

要求本文

データ ソース、インデックス、スキルセットはインデクサーの定義の一部ですが、それぞれが独立したコンポーネントであり、さまざまな組み合わせで使用できます。 たとえば、複数のインデクサーで同じデータ ソースを使用したり、複数のインデクサーで同じインデックスを使用したり、単一のインデックスに書き込む複数のインデクサーを使用したりできます。

次の JSON は、定義のメイン部分の大まかな表現です。

{   
    "name" : (optional on PUT; required on POST) "Name of the indexer",  
    "description" : (optional) "Anything you want, or nothing at all", 
    "dataSourceName" : (required) "Name of an existing data source",  
    "targetIndexName" : (required) "Name of an existing index",  
    "skillsetName" : (required for AI enrichment) "Name of an existing skillset",
    "disabled" : (optional) Boolean value indicating whether the indexer is disabled. False by default,
    "schedule" : (optional but runs once immediately if unspecified) { ... },  
    "parameters": { (optional)
       "batchSize": null,
       "maxFailedItems": 0,
       "maxFailedItemsPerBatch": 0,
       "base64EncodeKeys": null,
       "configuration": { (optional, mostly specific to the data source)
            "executionEnvironment": null
        }
      }, 
    "fieldMappings" : (optional) { ... },
    "outputFieldMappings" : (required for AI enrichment) { ... },
    "encryptionKey":(optional) { }
} 

要求には次のプロパティが含まれます。

BLOB の構成パラメーター

Azure Blob のインデックス付けなど、一部のパラメーターは特定のインデクサーにしかありません。

Azure Cosmos DB 構成パラメーター

次のパラメーターは、Cosmos DB インデクサーに固有です。

Azure SQL構成パラメーター

Azure SQL Database に固有のパラメーターを次に示します。

Response

要求成功の場合: 201 作成されました。

例

例: スケジュールパラメーターとジェネリック パラメーターを持つインデクサー

2021 年 1 月 1 日 (UTC) に開始され、1 時間ごとに実行されるスケジュールで、データ ソースordersによってordersds参照されるテーブルからインデックスにデータをコピーするインデクサーを作成します。 インデックス作成に失敗した項目が各バッチで 5 つ以下で、合計で 10 以下あれば、各インデクサーの呼び出しは成功となります。

{
    "name" : "myindexer",  
    "description" : "a cool indexer",  
    "dataSourceName" : "ordersds",  
    "targetIndexName" : "orders",  
    "schedule" : { "interval" : "PT1H", "startTime" : "2021-01-01T00:00:00Z" },  
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 5 }  
}

例: BLOB パラメーターを持つインデクサー

必要に応じて、インデクサーに、実行時の動作を変更する構成パラメーターを指定できます。 構成パラメーターはインデクサー要求でコンマ区切りであり、データ ソースの種類に固有です。 次の構成パラメーターは、BLOB のインデックス作成に使用する手順を示しています。

  {
    "name" : "my-blob-indexer-for-cognitive-search",
    ... other indexer properties
    "parameters" : 
      { 
      "maxFailedItems" : "15", 
      "batchSize" : "100", 
      "configuration" : 
          { 
          "parsingMode" : "json", 
          "indexedFileNameExtensions" : ".json, .jpg, .png",
          "imageAction" : "generateNormalizedImages",
          "dataToExtract" : "contentAndMetadata" ,
          "executionEnvironment": "Standard"
          } 
      }
  }

例: フィールド マッピングを使用したインデクサー

ソース テーブルのフィールド _id を "id" 検索インデックスのフィールドにマップします。 Azure AI Search では、フィールド名をアンダースコアで始めることはできません。 フィールド マッピングでは、名前の不一致を解決できます。 ソースとターゲットの両方のフィールド名で大文字と小文字が区別されます。 詳細については、フィールドのマッピングと変換に関する記事をご覧ください。

"fieldMappings" : [
    { "sourceFieldName" : "_id", "targetFieldName" : "id" },
    { "sourceFieldName" : "_timestamp", "targetFieldName" : "timestamp" }
]

例: AI エンリッチメントを使用したインデクサー

と outputFieldMappingsへの参照によって示される AI エンリッチメントをskillset示します。 スキルセットは高水準リソースであり、個別に定義されます。 この例は、 AI エンリッチメント チュートリアルのインデクサー定義の省略形です。

{
  "name":"demoindexer",	
  "dataSourceName" : "demodata",
  "targetIndexName" : "demoindex",
  "skillsetName" : "demoskillset",
  "fieldMappings" : [
    {
        "sourceFieldName" : "content",
        "targetFieldName" : "content"
    }
   ],
  "outputFieldMappings" : 
  [
    {
        "sourceFieldName" : "/document/organizations", 
        "targetFieldName" : "organizations"
    },
  ],
  "parameters":
  {
  	"maxFailedItems":-1,
  	"configuration": 
    {
    "dataToExtract": "contentAndMetadata",
    "imageAction": "generateNormalizedImages"
    }
  }
}

例: スキルセットと出力フィールド マッピングを使用したインデクサー

スキルセットがインデクサーにバインドされている AI エンリッチメント シナリオでは、 を追加 outputFieldMappings して、コンテンツをインデックス内の検索可能なフィールドに提供するエンリッチメント ステップの出力を関連付ける必要があります。 sourceFieldNameはエンリッチメント ツリー内のノードです。 ソース ドキュメント内の 2 つの異なるフィールドからのエンリッチメント中に構築された複合構造である可能性があります。 は targetFieldName 検索インデックスのフィールドです。 詳細については、「 スキルセットから出力フィールドをマップする方法」を参照してください。

"outputFieldMappings" : [
      {
        "sourceFieldName" : "/document/organizations", 
        "targetFieldName" : "organizations"
      },
      {
        "sourceFieldName" : "/document/pages/*/keyPhrases/*", 
        "targetFieldName" : "keyphrases"
      },
      {
          "sourceFieldName": "/document/languageCode",
          "targetFieldName": "language",
          "mappingFunction": null
      }      
  ]

例: 暗号化キー

暗号化キーは、追加の暗号化に使用されるカスタマー マネージド キーです。 詳細については、「Azure Key Vault でのカスタマー マネージド キーを使用した暗号化」を参照してください。

{
    "name" : "myindexer",  
    "description" : "a cool indexer",  
    "dataSourceName" : "ordersds",  
    "targetIndexName" : "orders",  
    "schedule" : { "interval" : "PT1H", "startTime" : "2021-01-01T00:00:00Z" },  
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 5 },
    "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": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}

関連項目

• インデクサーの概要
• インデクサーの作成
• AI エンリッチメントの概要
• クイック スタート: ポータルで AI エンリッチメントを試す
• フィールドをマップする方法 (AI エンリッチメント)