Azure AI 検索でのコンカレンシーの管理

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

インデックスやデータソースなどの Azure AI Search リソースを管理するときは、リソースを安全に更新すること (特にアプリケーションの複数の異なるコンポーネントによってリソースが同時にアクセスされる場合) が重要です。 2 つのクライアントが調整なしでリソースを同時に更新すると、競合状態になる可能性があります。これを防ぐために、Azure AI 検索ではオプティミスティック同時実行制御モデルが使用されます。リソースのロックはありません。代わりに、偶発的な上書きを避ける要求を作成できるよう、リソースのバージョンを識別する ETag がすべてのリソースに存在します。

しくみ

オプティミスティックコンカレンシーは、インデックス、インデクサー、データソース、スキルセット、および synonymMap リソースに書き込む API 呼び出しでのアクセス条件チェックによって実装されます。

すべてのリソースには、オブジェクトのバージョン情報を提供するエンティティタグ (ETag) があります。最初に ETag をチェックして、リソースの ETag がローカルコピーと一致することを確認することにより、典型的なワークフロー (取得、ローカル変更、更新) における同時更新を回避できます。

REST API では、要求ヘッダーで ETag を使用します。
Azure SDK for .NET では、accessCondition オブジェクトを通じて ETag を設定し、リソースの If-Match | If-Match-None ヘッダーを設定します。 ETag を使用するオブジェクト (SynonymMap.ETag や SearchIndex.ETag など) には、accessCondition オブジェクトがあります。

リソースを更新するたびに、その ETag が自動的に変化します。コンカレンシー管理を実装するときに行うのは、リモートリソースの ETag が、クライアントで変更したリソースのコピーの ETag と同じであることを要求する前提条件を更新要求に課すことだけです。別のプロセスによってリモートリソースが変更された場合、ETag は前提条件と一致せず、要求は HTTP 412 で失敗します。 .NET SDK を使用している場合、この失敗は IsAccessConditionFailed() 拡張メソッドが true を返す例外として明示されます。

Note

コンカレンシーのメカニズムは 1 つしかありません。どの API または SDK がリソース更新に使用されるかに関係なく、常にそのメカニズムが使用されます。

例

次のコードは、更新操作のオプティミスティック同時実行制御を示しています。オブジェクトの ETag が以前の更新によって変更されたため、2 回目の更新に失敗します。具体的には、要求ヘッダーの ETag がオブジェクトの ETag と一致しなくなった場合、検索サービスは状態コード 400 (無効な要求) を返し、更新は失敗します。

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using System;
using System.Net;
using System.Threading.Tasks;

namespace AzureSearch.SDKHowTo
{
    class Program
    {
        // This sample shows how ETags work by performing conditional updates and deletes
        // on an Azure Search index.
        static void Main(string[] args)
        {
            string serviceName = "PLACEHOLDER FOR YOUR SEARCH SERVICE NAME";
            string apiKey = "PLACEHOLDER FOR YOUR SEARCH SERVICE ADMIN API KEY";

            // Create a SearchIndexClient to send create/delete index commands
            Uri serviceEndpoint = new Uri($"https://{serviceName}.search.windows.net/");
            AzureKeyCredential credential = new AzureKeyCredential(apiKey);
            SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, credential);

            // Delete index if it exists
            Console.WriteLine("Check for index and delete if it already exists...\n");
            DeleteTestIndexIfExists(adminClient);

            // Every top-level resource in Azure Search has an associated ETag that keeps track of which version
            // of the resource you're working on. When you first create a resource such as an index, its ETag is
            // empty.
            SearchIndex index = DefineTestIndex();

            Console.WriteLine(
                $"Test searchIndex hasn't been created yet, so its ETag should be blank. ETag: '{index.ETag}'");

            // Once the resource exists in Azure Search, its ETag is populated. Make sure to use the object
            // returned by the SearchIndexClient. Otherwise, you will still have the old object with the
            // blank ETag.
            Console.WriteLine("Creating index...\n");
            index = adminClient.CreateIndex(index);
            Console.WriteLine($"Test index created; Its ETag should be populated. ETag: '{index.ETag}'");


            // ETags prevent concurrent updates to the same resource. If another
            // client tries to update the resource, it will fail as long as all clients are using the right
            // access conditions.
            SearchIndex indexForClientA = index;
            SearchIndex indexForClientB = adminClient.GetIndex("test-idx");

            Console.WriteLine("Simulating concurrent update. To start, clients A and B see the same ETag.");
            Console.WriteLine($"ClientA ETag: '{indexForClientA.ETag}' ClientB ETag: '{indexForClientB.ETag}'");

            // indexForClientA successfully updates the index.
            indexForClientA.Fields.Add(new SearchField("a", SearchFieldDataType.Int32));
            indexForClientA = adminClient.CreateOrUpdateIndex(indexForClientA);

            Console.WriteLine($"Client A updates test-idx by adding a new field. The new ETag for test-idx is: '{indexForClientA.ETag}'");

            // indexForClientB tries to update the index, but fails due to the ETag check.
            try
            {
                indexForClientB.Fields.Add(new SearchField("b", SearchFieldDataType.Boolean));
                adminClient.CreateOrUpdateIndex(indexForClientB);

                Console.WriteLine("Whoops; This shouldn't happen");
                Environment.Exit(1);
            }
            catch (RequestFailedException e) when (e.Status == 400)
            {
                Console.WriteLine("Client B failed to update the index, as expected.");
            }

            // Uncomment the next line to remove test-idx
            //adminClient.DeleteIndex("test-idx");
            Console.WriteLine("Complete.  Press any key to end application...\n");
            Console.ReadKey();
        }


        private static void DeleteTestIndexIfExists(SearchIndexClient adminClient)
        {
            try
            {
                if (adminClient.GetIndex("test-idx") != null)
                {
                    adminClient.DeleteIndex("test-idx");
                }
            }
            catch (RequestFailedException e) when (e.Status == 404)
            {
                //if an exception occurred and status is "Not Found", this is working as expected
                Console.WriteLine("Failed to find index and this is because it's not there.");
            }
        }

        private static SearchIndex DefineTestIndex() =>
            new SearchIndex("test-idx", new[] { new SearchField("id", SearchFieldDataType.String) { IsKey = true } });
    }
}

設計パターン

オプティミスティック同時実行制御を実装するための設計パターンには、アクセス条件チェック、アクセス条件のテストを再試行し、変更の再適用を試みる前に更新済みリソースを必要に応じて取得するループを含めるようにします。

このコードスニペットでは、既に存在するインデックスに synonymMap を追加する例を示します。

スニペットでは "hotels" インデックスを取得し、更新操作時にオブジェクトのバージョンをチェックし、条件に適合しない場合は例外をスローした後、操作を (最大 3 回) 再試行します。この際、最新バージョンを取得するために、まずサーバーからインデックスを取得します。

private static void EnableSynonymsInHotelsIndexSafely(SearchServiceClient serviceClient)
{
    int MaxNumTries = 3;

    for (int i = 0; i < MaxNumTries; ++i)
    {
        try
        {
            Index index = serviceClient.Indexes.Get("hotels");
            index = AddSynonymMapsToFields(index);

            // The IfNotChanged condition ensures that the index is updated only if the ETags match.
            serviceClient.Indexes.CreateOrUpdate(index, accessCondition: AccessCondition.IfNotChanged(index));

            Console.WriteLine("Updated the index successfully.\n");
            break;
        }
        catch (Exception e) when (e.IsAccessConditionFailed())
        {
            Console.WriteLine($"Index update failed : {e.Message}. Attempt({i}/{MaxNumTries}).\n");
        }
    }
}

private static Index AddSynonymMapsToFields(Index index)
{
    index.Fields.First(f => f.Name == "category").SynonymMaps = new[] { "desc-synonymmap" };
    index.Fields.First(f => f.Name == "tags").SynonymMaps = new[] { "desc-synonymmap" };
    return index;
}

次の方法で共有

Azure AI 検索でのコンカレンシーの管理

しくみ

例

設計パターン

関連項目

フィードバック

その他のリソース