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

[アーティクル]
09/03/2024

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

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

前提条件

Azure Table Storage
テキストを含むテーブル。バイナリデータがある場合は、画像分析向けに AI エンリッチメントを検討してください。
Azure Storage に対する読み取りアクセス許可。 "フルアクセス" の接続文字列には、コンテンツへのアクセスを許可するキーが含まれますが、Azure ロールを使用している場合は、検索サービスのマネージド ID にデータおよび閲覧者のアクセス許可があることを確認してください。
この記事に示すような REST 呼び出しを作成する場合は、REST クライアントを使用します。

データソースを定義する

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

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

 POST https://[service name].search.windows.net/datasources?api-version=2024-07-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
 }

"type" を "azuretable" に指定します (必須)。
"credentials" を Azure Storage 接続文字列に設定します。続く部分は、サポートされている形式を記述します。
"container" をテーブルの名前に設定します。
必要に応じて "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> 条件を定期的に更新します。
- この方法では、全インデックスの再作成をトリガーする必要がある場合は、インデクサーのリセットに加えてデータソースクエリをリセットします。

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

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

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

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

ドキュメントキーフィールド ("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"
   }
]
```
次に、インデックスに必要な他のエンティティフィールドを追加します。たとえば、エンティティが次の例のような場合、検索インデックスにはフィールドの値を受け取るために HotelName、Description、Category のフィールドが必要です。

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

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

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

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

POST https://[service name].search.windows.net/indexers?api-version=2024-07-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,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

フィールドの名前または種類に違いがある、または検索インデックスで複数のソースフィールドのバージョンが必要な場合、フィールドマッピングを定義します。ターゲットフィールドは、検索インデックス内のフィールドの名前です。
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Description",
     "targetFieldName" : "HotelDescription"
   }
]
```
その他のプロパティについては、「インデクサーの作成方法」を参照してください。

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

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

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-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 からコンテンツをプルするインデクサーを使用する場合に参照できます。

次の方法で共有

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

前提条件

データソースを定義する

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

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

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

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

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

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

データ ソースを定義する

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

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

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

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

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

次のステップ

フィードバック

その他のリソース

データソースを定義する

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