Azure Cognitive Search を使用して Azure Table Storage からテーブルにインデックスを作成する方法How to index tables from Azure Table storage with Azure Cognitive Search

この記事では、Azure Cognitive Search を使用して、Azure Table Storage に格納されているデータのインデックスを作成する方法を示します。This article shows how to use Azure Cognitive Search to index data stored in Azure Table storage.

Azure Table Storage のインデックスを設定するSet up Azure Table storage indexing

次のリソースを使用して、Azure Table Storage のインデクサーを設定できます。You can set up an Azure Table storage indexer by using these resources:

ここでは、REST API を使用したフローについて説明します。Here we demonstrate the flow by using the REST API.

手順 1:データソースの作成Step 1: Create a datasource

データ ソースは、インデックスを作成するデータ、データにアクセスするために必要な資格情報、および Azure Cognitive Search がデータの変更を効率よく識別できるようにするポリシーを指定します。A datasource specifies which data to index, the credentials needed to access the data, and the policies that enable Azure Cognitive Search to efficiently identify changes in the data.

テーブルのインデックス作成では、次のプロパティがデータ ソースに必要です。For table indexing, the datasource must have the following properties:

  • name は、Search サービス内のデータ ソースの一意の名前です。name is the unique name of the datasource within your search service.
  • typeazuretable である必要があります。type must be azuretable.
  • credentials パラメーターは、ストレージ アカウントの接続文字列が含まれます。credentials parameter contains the storage account connection string. 詳しくは、「資格情報を指定する方法」セクションをご覧ください。See the Specify credentials section for details.
  • container はテーブル名とオプションのクエリを設定します。container sets the table name and an optional query.
    • name パラメーターを使用して、テーブル名を指定します。Specify the table name by using the name parameter.
    • 必要に応じて query パラメーターを使用して、クエリを指定します。Optionally, specify a query by using the query parameter.


可能な場合は、パフォーマンス向上のために PartitionKey でフィルターを使用してください。Whenever possible, use a filter on PartitionKey for better performance. その他のクエリはフル テーブル スキャンを実行するため、規模の大きなテーブルではパフォーマンスが下がります。Any other query does a full table scan, resulting in poor performance for large tables. 詳しくは、「パフォーマンスに関する考慮事項」セクションをご覧ください。See the Performance considerations section.

データ ソースを作成するには:To create a datasource:

    POST https://[service name]
    Content-Type: application/json
    api-key: [admin key]

        "name" : "table-datasource",
        "type" : "azuretable",
        "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
        "container" : { "name" : "my-table", "query" : "PartitionKey eq '123'" }

データ ソース作成 API の詳細については、「データ ソースの作成」をご覧ください。For more information on the Create Datasource API, see Create Datasource.

資格情報を指定する方法Ways to specify credentials

次のいずれかの方法でテーブルに対して資格情報を指定できます。You can provide the credentials for the table in one of these ways:

  • マネージド ID の接続文字列:ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/; この接続文字列にはアカウント キーは必要ありませんが、マネージド ID を使用して、Azure Storage アカウントへの接続を設定する方法に関する指示に従う必要があります。Managed identity connection string: ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/; This connection string does not require an account key, but you must follow the instructions for Setting up a connection to an Azure Storage account using a managed identity.
  • フル アクセス ストレージ アカウントの接続文字列: DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key> この接続文字列は、ストレージ アカウント ブレード > [設定] > [キー] と選択する (クラシック ストレージ アカウントの場合) か、 [設定] > [アクセス キー] と選択する (Azure Resource Manager ストレージ アカウントの場合) ことで Azure Portal から取得できます。Full access storage account connection string: DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key> You can get the connection string from the Azure portal by going to the Storage account blade > Settings > Keys (for classic storage accounts) or Settings > Access keys (for Azure Resource Manager storage accounts).
  • ストレージ アカウントの共有アクセス署名の接続文字列: TableEndpoint=https://<your account>;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=t&sp=rl 共有アクセス署名には、コンテナー (この場合はテーブル) 上およびオブジェクト (テーブル行) にリストおよび読み取りアクセス許可が必要です。Storage account shared access signature connection string: TableEndpoint=https://<your account>;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=t&sp=rl The shared access signature should have the list and read permissions on containers (tables in this case) and objects (table rows).
  • テーブルの共有アクセス署名: ContainerSharedAccessUri=https://<your storage account><table name>?tn=<table name>&sv=2016-05-31&sig=<the signature>&se=<the validity end time>&sp=r 共有アクセス署名には、テーブルに対するクエリ (読み取り) アクセス許可が必要です。Table shared access signature: ContainerSharedAccessUri=https://<your storage account><table name>?tn=<table name>&sv=2016-05-31&sig=<the signature>&se=<the validity end time>&sp=r The shared access signature should have query (read) permissions on the table.

ストレージの共有アクセス署名の詳細については、「Shared Access Signature (SAS) の使用」を参照してください。For more information on storage shared access signatures, see Using shared access signatures.


共有アクセス署名の資格情報を使用する場合は、その有効期限が切れないように、データ ソースの資格情報を更新された署名で定期的に更新する必要があります。If you use shared access signature credentials, you will need to update the datasource credentials periodically with renewed signatures to prevent their expiration. 共有アクセス署名の資格情報の有効期限が切れた場合、インデクサーは失敗し、「接続文字列で指定された資格情報が無効か期限が切れています」のようなエラー メッセージが表示されます。If shared access signature credentials expire, the indexer fails with an error message similar to "Credentials provided in the connection string are invalid or have expired."

手順 2:インデックスを作成するStep 2: Create an index

インデックスは、検索に使用する、ドキュメント内のフィールド、属性、およびその他の構成要素を指定します。The index specifies the fields in a document, the attributes, and other constructs that shape the search experience.

インデックスを作成するには:To create an index:

    POST https://[service name]
    Content-Type: application/json
    api-key: [admin key]

          "name" : "my-target-index",
          "fields": [
            { "name": "key", "type": "Edm.String", "key": true, "searchable": false },
            { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }

インデックスの作成の詳細については、インデックスの作成に関する記事をご覧ください。For more information on creating indexes, see Create Index.

手順 3:インデクサーの作成Step 3: Create an indexer

インデクサーはデータ ソースをターゲットの検索インデックスに接続し、データ更新を自動化するスケジュールを提供します。An indexer connects a datasource with a target search index and provides a schedule to automate the data refresh.

インデックスとデータ ソースを作成した後、インデクサーを作成できます。After the index and datasource are created, you're ready to create the indexer:

    POST https://[service name]
    Content-Type: application/json
    api-key: [admin key]

      "name" : "table-indexer",
      "dataSourceName" : "table-datasource",
      "targetIndexName" : "my-target-index",
      "schedule" : { "interval" : "PT2H" }

このインデクサーは、2 時間ごとに実行されます This indexer runs every two hours. (スケジュール間隔は "PT2H"に設定されます)。インデクサーを 30 分ごとに実行するには、間隔を "PT30M" に設定します。(The schedule interval is set to "PT2H".) To run an indexer every 30 minutes, set the interval to "PT30M". サポートされている最短の間隔は 5 分です。The shortest supported interval is five minutes. スケジュールは省略可能です。省略した場合、インデクサーは作成時に一度だけ実行されます。The schedule is optional; if omitted, an indexer runs only once when it's created. ただし、いつでもオンデマンドでインデクサーを実行できます。However, you can run an indexer on demand at any time.

インデクサー作成 API の詳細については、インデクサーの作成に関するページをご覧ください。For more information on the Create Indexer API, see Create Indexer.

インデクサーのスケジュールの定義の詳細については、Azure Cognitive Search のインデクサーのスケジュールを設定する方法に関する記事を参照してください。For more information about defining indexer schedules see How to schedule indexers for Azure Cognitive Search.

さまざまなフィールド名を操作するDeal with different field names

既存のインデックス内のフィールド名が、テーブルのプロパティ名と異なることがあります。Sometimes, the field names in your existing index are different from the property names in your table. テーブルのプロパティ名は、フィールド マッピングを使用して、検索インデックス内のフィールド名に対応付けることができます。You can use field mappings to map the property names from the table to the field names in your search index. フィールド マッピングの詳細については、データ ソースと検索インデックスの橋渡し役としての Azure Cognitive Search インデクサー フィールド マッピングに関する記事を参照してください。To learn more about field mappings, see Azure Cognitive Search indexer field mappings bridge the differences between datasources and search indexes.

ドキュメント キーを処理するHandle document keys

Azure Cognitive Search では、ドキュメントがそのキーによって一意に識別されます。In Azure Cognitive Search, the document key uniquely identifies a document. それぞれの検索インデックスには、 Edm.String型のキー フィールドが 1 つだけ必要です。Every search index must have exactly one key field of type Edm.String. キー フィールドは、インデックスに追加するドキュメントごとに必要です The key field is required for each document that is being added to the index. (実際のところ、これは唯一の必須フィールドです)。(In fact, it's the only required field.)

テーブル行には複合キーがあるため、Azure Cognitive Search では、パーティション キーと行キーの値が連結された Key と呼ばれる合成フィールドが生成されます。Because table rows have a compound key, Azure Cognitive Search generates a synthetic field called Key that is a concatenation of partition key and row key values. たとえば、行の PartitionKey が PK1 で、RowKey が RK1 の場合、Key フィールドの値は PK1RK1 です。For example, if a row’s PartitionKey is PK1 and RowKey is RK1, then the Key field's value is PK1RK1.


Key 値には、ドキュメント キーでは無効な文字、たとえばダッシュを含めることができます。The Key value may contain characters that are invalid in document keys, such as dashes. 無効な文字を扱うには、 base64Encode フィールド マッピング関数を使用します。You can deal with invalid characters by using the base64Encode field mapping function. これを行う場合は、Lookup などの API 呼び出しでドキュメント キーを渡す際に、必ず URL の安全な Base64 エンコードを使用する点にも注意してください。If you do this, remember to also use URL-safe Base64 encoding when passing document keys in API calls such as Lookup.

インデックスの増分作成と削除の検出Incremental indexing and deletion detection

スケジュールに従って実行するようにテーブルのインデクサーを設定すると、行の Timestamp 値に従って、新しい行または更新された行のみでインデックスが再作成されます。When you set up a table indexer to run on a schedule, it reindexes only new or updated rows, as determined by a row’s Timestamp value. 変更検出ポリシーを指定する必要はありません。You don’t have to specify a change detection policy. 増分インデックス作成が自動的に有効になります。Incremental indexing is enabled for you automatically.

一部のドキュメントをインデックスを削除する必要があることを示すには、論理的な削除を使用できます。To indicate that certain documents must be removed from the index, you can use a soft delete strategy. 行を削除する代わりに、プロパティを追加してそれが削除されていることを示し、データソースに論理的な削除のポリシーを設定します。Instead of deleting a row, add a property to indicate that it's deleted, and set up a soft deletion detection policy on the datasource. たとえば、次のポリシーは値 "true" が指定されたプロパティ IsDeleted がある行を削除されているものと見なします。For example, the following policy considers that a row is deleted if the row has a property IsDeleted with the value "true":

    PUT https://[service name]
    Content-Type: application/json
    api-key: [admin key]

        "name" : "my-table-datasource",
        "type" : "azuretable",
        "credentials" : { "connectionString" : "<your storage connection string>" },
        "container" : { "name" : "table name", "query" : "<query>" },
        "dataDeletionDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy", "softDeleteColumnName" : "IsDeleted", "softDeleteMarkerValue" : "true" }

パフォーマンスに関する考慮事項Performance considerations

既定では、Azure Cognitive Search は Timestamp >= HighWaterMarkValue というクエリ フィルターを使用します。By default, Azure Cognitive Search uses the following query filter: Timestamp >= HighWaterMarkValue. Azure のテーブルの Timestamp フィールドにはセカンダリ インデックスがないため、この種類のクエリはフル テーブル スキャンを必要とし、規模の大きなテーブルでは速度が低下します。Because Azure tables don’t have a secondary index on the Timestamp field, this type of query requires a full table scan and is therefore slow for large tables.

テーブルのインデックス作成のパフォーマンスを向上させる可能性のある 2 つの方法を紹介します。Here are two possible approaches for improving table indexing performance. どちらの方法もテーブルのパーティションを使用します。Both of these approaches rely on using table partitions:

  • データを複数のパーティション範囲に自然に分割できる場合は、各パーティション範囲にデータソースと対応するインデクサーを作成します。If your data can naturally be partitioned into several partition ranges, create a datasource and a corresponding indexer for each partition range. これで各インデクサーが特定のパーティション範囲のみを処理するようになるため、クエリのパフォーマンスが向上します。Each indexer now has to process only a specific partition range, resulting in better query performance. インデックスを作成する必要があるデータに固定のパーティションが少数ある場合、各インデクサーはパーティションのスキャンのみを実行するため、パフォーマンスが向上します。If the data that needs to be indexed has a small number of fixed partitions, even better: each indexer only does a partition scan. たとえば、キーが 000 から 100 の範囲のパーティションを処理するデータソースを作成するには、次のようなクエリを使用します。For example, to create a datasource for processing a partition range with keys from 000 to 100, use a query like this:

    "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }
  • データが時間によって分割されている (新しいパーティションを毎日または毎週作成するなどの) 場合は、次の方法を検討してください。If your data is partitioned by time (for example, you create a new partition every day or week), consider the following approach:

    • (PartitionKey ge <TimeStamp>) and (other filters) の形式のクエリを使用します。Use a query of the form: (PartitionKey ge <TimeStamp>) and (other filters).
    • インデクサーの進行状況を Get Indexer Status API を使用して監視し、直近の成功した高基準値に基づいてクエリの <TimeStamp> 条件を定期的に更新します。Monitor indexer progress by using Get Indexer Status API, and periodically update the <TimeStamp> condition of the query based on the latest successful high-water-mark value.
    • この方法では、全インデックスの再作成をトリガーする必要がある場合は、インデクサーのリセットに加えてデータソース クエリをリセットする必要があります。With this approach, if you need to trigger a complete reindexing, you need to reset the datasource query in addition to resetting the indexer.

Azure Cognitive Search の品質向上にご協力くださいHelp us make Azure Cognitive Search better

ご希望の機能や品質向上のアイデアがありましたら、UserVoice サイトにぜひお寄せください。If you have feature requests or ideas for improvements, submit them on our UserVoice site.