Azure Table Storage からのデータへのインデックス付け

  • [アーティクル]

この記事では、インデクサーを構成する方法について学習します。これにより、Azure Table Storage からコンテンツをインポートし、Azure AI Search でその検索ができるようになります。 インデクサーへの入力は、1 つのテーブル内のエンティティです。 出力は、検索可能なコンテンツとメタデータが個々のフィールドに格納される検索インデックスです。

「インデクサーの作成」について補足するこの記事では、Azure Table Storage からのインデックス作成に固有の情報を扱います。 REST API を使用して、すべてのインデクサーに共通する 3 部構成のワークフロー (データ ソースの作成、インデックスの作成、インデクサーの作成) を示します。 データ抽出は、インデクサーの作成要求を送信したときに発生します。

前提条件

  • Azure Table Storage

  • テキストを含むテーブル。 バイナリ データがある場合は、画像分析向けに AI エンリッチメントを検討してください。

  • Azure Storage に対する読み取りアクセス許可。 "フル アクセス" の接続文字列には、コンテンツへのアクセスを許可するキーが含まれますが、Azure ロールを使用している場合は、検索サービスのマネージド ID にデータおよび閲覧者のアクセス許可があることを確認してください。

  • この記事に示すような REST 呼び出しを作成する場合は、REST クライアントを使用します。

データ ソースを定義する

データ ソース定義では、インデックスを付けるソース データ、資格情報、変更を識別するためのポリシーを指定します。 データ ソースは、複数のインデクサーで使用できる独立したリソースです。

  1. データ ソースを作成または更新してその定義を設定します。

     POST https://[service name].search.windows.net/datasources?api-version=2023-11-01 
 {
     "name": "my-table-storage-ds",
     "description": null,
     "type": "azuretable",
     "subtype": null,
     "credentials": {
        "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>"
     },
     "container": {
        "name": "my-table-in-azure-storage",
        "query": ""
     },
     "dataChangeDetectionPolicy": null,
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
 }

  2. "type" を "azuretable" に指定します (必須)。

  3. "credentials" を Azure Storage 接続文字列に設定します。 続く部分は、サポートされている形式を記述します。

  4. "container" をテーブルの名前に設定します。

  5. 必要に応じて "query" を PartitionKey のフィルターに設定します。 このプロパティの設定は、パフォーマンスを向上させるベスト プラクティスです。 "query" が null の場合、インデクサーにより完全なテーブル スキャンが実行されるため、テーブルが大きい場合はパフォーマンスが低下する可能性があります。

ソース ドキュメントに削除対象のフラグが設定されているときにインデクサーで検索ドキュメントを削除する場合は、データ ソースの定義に論理的な削除ポリシーを含めることもできます。

サポートされている資格情報と接続文字列

インデクサーがテーブルへの接続に使用する接続は次のとおりです。

フル アクセス ストレージ アカウントの接続文字列
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
Azure portal の Storage アカウント ページで左側のナビゲーション ウィンドウの [アクセス キー] を選択して接続文字列を取得できます。 キーだけではなく、完全な接続文字列を選択してください。
マネージド ID の接続文字列
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }
この接続文字列にアカウント キーは必要ありませんが、マネージド ID を使用して接続するように検索サービスを前もって構成しておく必要があります。
ストレージ アカウントの Shared Access Signature** (SAS) の接続文字列
{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }
SAS にはテーブルとエンティティのリスト権限および読み取りアクセス許可が必要です。
コンテナーの Shared Access Signature
{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }
SAS にはコンテナー上にリストおよび読み取りアクセス許可が必要です。 詳細については、Shared Access Signatues の使用に関するページを参照してください。

Note

SAS の資格情報を使用する場合は、その有効期限が切れないように、データ ソースの資格情報を更新された署名で定期的に更新する必要があります。 SAS の資格情報の有効期限が切れた場合、インデクサーは失敗し、「接続文字列で指定された資格情報が無効か期限が切れています」のようなエラー メッセージが表示されます。

パフォーマンスの向上に役立つパーティション

既定では、Azure AI Search は Timestamp >= HighWaterMarkValue 内部クエリ フィルターを使用して、前回の実行以降に更新されたソース エンティティを追跡します。 Azure のテーブルの Timestamp フィールドにはセカンダリ インデックスがないため、この種類のクエリはフル テーブル スキャンを必要とし、規模の大きなテーブルでは速度が低下します。

フル スキャンを回避するには、テーブル パーティションを使用して各インデクサー ジョブのスコープを絞り込むことができます。

  • データを複数のパーティション範囲に自然に分割できる場合は、各パーティション範囲にデータソースと対応するインデクサーを作成します。 これで各インデクサーが特定のパーティション範囲のみを処理するようになるため、クエリのパフォーマンスが向上します。 インデックスを作成する必要があるデータに固定のパーティションが少数ある場合、各インデクサーはパーティションのスキャンのみを実行するため、パフォーマンスが向上します。

    たとえば、キーが 000 から 100 の範囲のパーティションを処理するデータソースを作成するには、次のようなクエリを使用します: "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }

  • データが時間によって分割されている (新しいパーティションを毎日または毎週作成するなどの) 場合は、次の方法を検討してください。

    • データ ソースの定義で、次の例のようなクエリを指定します: (PartitionKey ge <TimeStamp>) and (other filters)。

    • インデクサーの進行状況を Get Indexer Status API を使用して監視し、直近の成功した高基準値に基づいてクエリの <TimeStamp> 条件を定期的に更新します。

    • この方法では、全インデックスの再作成をトリガーする必要がある場合は、インデクサーのリセットに加えてデータ ソース クエリをリセットします。

インデックスに検索フィールドを追加する

検索インデックスでは、テーブル エンティティのコンテンツとメタデータを検出するフィールドを追加します。

  1. インデックスを作成または更新して、エンティティからのコンテンツを格納する検索フィールドを定義します。

    POST https://[service name].search.windows.net/indexes?api-version=2023-11-01 
{
  "name" : "my-search-index",
  "fields": [
    { "name": "Key", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
  ]
}

  2. ドキュメント キー フィールド ("key": true) を作成しますが、インデクサーが自動的に設定できるようにします。 テーブル インデクサーにより、テーブルから連結されたパーティション キーと行キーがキー フィールドに設定されます。 たとえば、行の PartitionKey が 1 で、RowKey が 1_123 の場合、キーの値は 11_123 です。 パーティション キーが null の場合は、行キーが使用されます。

    データのインポート ウィザードを使用してインデックスを作成している場合、ポータルは検索インデックスの "キー" フィールドを推論し、暗黙的なフィールド マッピングを使用してソース フィールドとコピー先フィールドを接続します。 フィールドを自分で追加する必要はありません。また、フィールド マッピングを設定する必要はありません。

    REST API を使用していて、暗黙的なフィールド マッピングが必要な場合は、前の手順 ({ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }) に示したように、検索インデックス定義に "Key"という名前のドキュメント キー フィールドを作成します。 インデクサーは、フィールド マッピングを必要とせず、Key フィールドに自動的に入力します。

    検索インデックスに "Key" という名前のフィールドを使用したくない場合は、インデクサー定義にフィールド名を指定して明示的なフィールド マッピングを追加し、ソース フィールドを "Key" に設定します。

     "fieldMappings" : [
   {
     "sourceFieldName" : "Key",
     "targetFieldName" : "MyDocumentKeyFieldName"
   }
]

  3. 次に、インデックスに必要な他のエンティティ フィールドを追加します。 たとえば、エンティティが次の例のような場合、検索インデックスにはフィールドの値を受け取るために HotelName、Description、Category のフィールドが必要です。

    Screenshot of table content in Storage browser.

    同じ名前と互換性のあるデータ型を使用すると、フィールド マッピングの必要性を最小限に抑えることができます。 名前と型が同じ場合、インデクサーはデータ パスを自動的に決定できます。

テーブル インデクサーの構成と実行

インデックスとデータ ソースを用意した後、インデクサーを作成できるようになります。 インデクサーの構成では、実行時の動作を制御する入力、パラメーター、プロパティを指定します。

  1. 名前を指定し、データ ソースとターゲット インデックスを参照することで、インデクサーを作成または更新します。

    POST https://[service name].search.windows.net/indexers?api-version=2023-11-01
{
    "name" : "my-table-indexer",
    "dataSourceName" : "my-table-storage-ds",
    "targetIndexName" : "my-search-index",
    "disabled": null,
    "schedule": null,
    "parameters" : {
        "batchSize" : null,
        "maxFailedItems" : null,
        "maxFailedItemsPerBatch" : null,
        "base64EncodeKeys" : null,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

  2. フィールドの名前または種類に違いがある、または検索インデックスで複数のソース フィールドのバージョンが必要な場合、フィールド マッピングを定義します。 ターゲット フィールドは、検索インデックス内のフィールドの名前です。

     "fieldMappings" : [
   {
     "sourceFieldName" : "Description",
     "targetFieldName" : "HotelDescription"
   }
]

  3. その他のプロパティについては、「インデクサーの作成方法」を参照してください。

インデクサーは、作成されると自動的に実行されます。 これを防ぐには、"disabled" を true に設定します。 インデクサーの実行を制御するには、インデクサーをオンデマンドで実行するか、スケジュールを設定します。

インデクサーの状態を確認する

インデクサーの状態と実行履歴を監視するには、インデクサーの状態の取得要求を送信します。

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
  Content-Type: application/json  
  api-key: [admin key]

応答には、状態と処理された項目の数が含まれます。 次の例のように表示されます。

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2023-02-21T00:23:24.957Z",
            "endTime":"2023-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2023-02-21T00:23:24.957Z",
                "endTime":"2023-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

実行履歴には、最近完了した実行 50 件が含まれます。時系列の逆の順に並べられるため、最後の実行が最初に表示されます。

次のステップ

インデクサーの実行、状態の監視、インデクサーの実行のスケジュール設定を行う方法の詳細を参照してください。 次の記事は、Azure Storage からコンテンツをプルするインデクサーを使用する場合に参照できます。