Azure サービスの再試行ガイダンスRetry guidance for Azure services

ほとんどの Azure サービスとクライアント SDK には、再試行メカニズムが組み込まれています。Most Azure services and client SDKs include a retry mechanism. しかし、再試行メカニズムは、サービスごとにさまざまな特性や要件があるため一定ではなく、それぞれの再試行メカニズムは特定のサービスに合わせて調整されます。However, these differ because each service has different characteristics and requirements, and so each retry mechanism is tuned to a specific service. このガイドでは、主要な Azure サービスの再試行メカニズム機能の概要と、そのサービスに合わせて再試行メカニズムを使用、適合、または拡張するために役立つ情報を記載しています。This guide summarizes the retry mechanism features for the majority of Azure services, and includes information to help you use, adapt, or extend the retry mechanism for that service.

一時的なエラーの処理、およびサービスとリソースに対する接続と操作の再試行に関する一般的なガイダンスについては、再試行のガイダンスに関するページをご覧ください。For general guidance on handling transient faults, and retrying connections and operations against services and resources, see Retry guidance.

次の表は、このガイダンスで説明されている Azure サービスの再試行機能をまとめています。The following table summarizes the retry features for the Azure services described in this guidance.

サービスService 再試行機能Retry capabilities ポリシーの構成Policy configuration スコープScope テレメトリ機能Telemetry features
Azure Active DirectoryAzure Active Directory ADAL ライブラリのネイティブNative in ADAL library ADAL ライブラリに埋め込み済みEmbedded into ADAL library 内部Internal なしNone
Cosmos DBCosmos DB サービスでネイティブNative in service 構成不可Non-configurable グローバルGlobal TraceSourceTraceSource
Data Lake StoreData Lake Store クライアントでネイティブNative in client 構成不可Non-configurable 個々の操作Individual operations なしNone
Event HubsEvent Hubs クライアントでネイティブNative in client プログラムによるProgrammatic ClientClient なしNone
IoT HubIoT Hub クライアント SDK でネイティブNative in client SDK プログラムによるProgrammatic ClientClient なしNone
Azure Cache for RedisAzure Cache for Redis クライアントでネイティブNative in client プログラムによるProgrammatic ClientClient TextWriterTextWriter
SearchSearch クライアントでネイティブNative in client プログラムによるProgrammatic ClientClient ETW またはカスタムETW or Custom
Service BusService Bus クライアントでネイティブNative in client プログラムによるProgrammatic 名前空間マネージャー、メッセージング ファクトリ、およびクライアントNamespace Manager, Messaging Factory, and Client ETWETW
Service FabricService Fabric クライアントでネイティブNative in client プログラムによるProgrammatic ClientClient なしNone
ADO.NET を使用した SQL DatabaseSQL Database with ADO.NET PollyPolly 宣言型およびプログラムによるDeclarative and programmatic 1 つのステートメントまたはコードのブロックSingle statements or blocks of code CustomCustom
Entity Framework を使用した SQL DatabaseSQL Database with Entity Framework クライアントでネイティブNative in client プログラムによるProgrammatic AppDomain ごとにグローバルGlobal per AppDomain なしNone
Entity Framework Core を使用した SQL DatabaseSQL Database with Entity Framework Core クライアントでネイティブNative in client プログラムによるProgrammatic AppDomain ごとにグローバルGlobal per AppDomain なしNone
StorageStorage クライアントでネイティブNative in client プログラムによるProgrammatic クライアントと個々の操作Client and individual operations TraceSourceTraceSource

注意

Azure の組み込み再試行メカニズムのほとんどには、さまざまな種類のエラーや例外に対して異なる再試行ポリシーを適用する方法が現在のところありません。For most of the Azure built-in retry mechanisms, there is currently no way apply a different retry policy for different types of error or exception. 最適な平均パフォーマンスおよび可用性を提供するポリシーを構成する必要があります。You should configure a policy that provides the optimum average performance and availability. ポリシーを微調整する 1 つの方法は、ログ ファイルを分析して、発生する一時的エラーの種類を判別することです。One way to fine-tune the policy is to analyze log files to determine the type of transient faults that are occurring.

Azure Active DirectoryAzure Active Directory

Azure Active Directory (Azure AD) は、コア ディレクトリ サービス、拡張 ID 制御、セキュリティ、およびアプリケーション アクセス管理を結合した、包括的な ID 管理とアクセス管理のクラウド ソリューションです。Azure Active Directory (Azure AD) is a comprehensive identity and access management cloud solution that combines core directory services, advanced identity governance, security, and application access management. Azure AD は、一元化されたポリシーとルールに基づいてアプリケーションへのアクセス制御を実現するための、ID 管理プラットフォームを開発者に提供します。Azure AD also offers developers an identity management platform to deliver access control to their applications, based on centralized policy and rules.

注意

マネージド サービス ID エンドポイントにおける再試行ガイダンスについては、トークン取得の Azure VM マネージド サービス ID (MSI) を使用する方法に関するページをご覧ください。For retry guidance on Managed Service Identity endpoints, see How to use an Azure VM Managed Service Identity (MSI) for token acquisition.

再試行メカニズムRetry mechanism

Active Directory Authentication Library (ADAL) には、Azure Active Directory のための組み込み再試行メカニズムがあります。There is a built-in retry mechanism for Azure Active Directory in the Active Directory Authentication Library (ADAL). 予想外のロックアウトを避けるためには、サード パーティのライブラリとアプリケーション コードで失敗した接続の再試行を実行せず、ADAL で再試行を処理することをお勧めします。To avoid unexpected lockouts, we recommend that third-party libraries and application code do not retry failed connections, but allow ADAL to handle retries.

再試行使用のガイダンスRetry usage guidance

Azure Active Directory を使用する場合は、次のガイドラインについて検討します。Consider the following guidelines when using Azure Active Directory:

  • 可能な場合は、ADAL ライブラリと組み込みの再試行サポートを使用してください。When possible, use the ADAL library and the built-in support for retries.
  • Azure Active Directory 用の REST API を使用している場合は、結果コードが 429 (Too Many Requests) または 5xx の範囲内のエラーの場合に操作を再試行してください。If you are using the REST API for Azure Active Directory, retry the operation if the result code is 429 (Too Many Requests) or an error in the 5xx range. その他のエラーの場合は、再試行しないでください。Do not retry for any other errors.
  • Azure Active Directory を使用するバッチのシナリオでは、指数バックオフ ポリシーの使用が推奨されています。An exponential back-off policy is recommended for use in batch scenarios with Azure Active Directory.

再試行操作を次の設定から始めることを検討してください。Consider starting with the following settings for retrying operations. これらの設定は汎用であり、操作を監視して、独自のシナリオに合うように値を微調整する必要があります。These settings are general purpose, and you should monitor the operations and fine-tune the values to suit your own scenario.

コンテキストContext サンプルのターゲット E2E
最大待機時間
Sample target E2E
max latency
再試行戦略Retry strategy 設定Settings Values 動作のしくみHow it works
対話型、UI、Interactive, UI,
またはフォアグラウンドor foreground
2 秒2 sec FixedIntervalFixedInterval 再試行回数Retry count
再試行間隔Retry interval
最初の高速再試行First fast retry
33
500 ミリ秒500 ms
truetrue
試行 1 - 0 秒の遅延Attempt 1 - delay 0 sec
試行 2 - 500 ミリ秒の遅延Attempt 2 - delay 500 ms
試行 3 - 500 ミリ秒の遅延Attempt 3 - delay 500 ms
バック グラウンドまたはBackground or
batch (バッチ)batch
60 秒60 sec ExponentialBackoffExponentialBackoff 再試行回数Retry count
最小バックオフMin back-off
最大バックオフMax back-off
差分バックオフDelta back-off
最初の高速再試行First fast retry
55
0 秒0 sec
60 秒60 sec
2 秒2 sec
falsefalse
試行 1 - 0 秒の遅延Attempt 1 - delay 0 sec
試行 2 - 最大 2 秒の遅延Attempt 2 - delay ~2 sec
試行 3 - 最大 6 秒の遅延Attempt 3 - delay ~6 sec
試行 4 - 最大 14 秒の遅延Attempt 4 - delay ~14 sec
試行 5 - 最大 30 秒の遅延Attempt 5 - delay ~30 sec

詳細情報More information

Cosmos DBCosmos DB

Cosmos DB は、スキーマのない JSON データをサポートする完全に管理されたマルチモデル データベースです。Cosmos DB is a fully managed multi-model database that supports schemaless JSON data. これは構成可能で信頼性の高いパフォーマンスと、ネイティブの JavaScript トランザクション処理を提供し、クラウド用にエラスティックなスケーラビリティを備えて作成されています。It offers configurable and reliable performance, native JavaScript transactional processing, and is built for the cloud with elastic scale.

再試行メカニズムRetry mechanism

DocumentClient クラスによって、失敗した試行が自動的にもう一度実行されます。The DocumentClient class automatically retries failed attempts. 再試行回数と最大待機時間を設定するには、ConnectionPolicy.RetryOptions を構成します。To set the number of retries and the maximum wait time, configure ConnectionPolicy.RetryOptions. クライアントがスローする例外は、再試行ポリシーを超えているか、一時的なエラーでないかのいずれかです。Exceptions that the client raises are either beyond the retry policy or are not transient errors.

クライアントが Cosmos DB によってスロットルされると、HTTP 429 エラーが返されます。If Cosmos DB throttles the client, it returns an HTTP 429 error. DocumentClientException で状態コードを確認します。Check the status code in the DocumentClientException.

ポリシーの構成Policy configuration

次の表は、RetryOptions クラスの既定の設定を示しています。The following table shows the default settings for the RetryOptions class.

設定Setting 既定値Default value 説明Description
MaxRetryAttemptsOnThrottledRequestsMaxRetryAttemptsOnThrottledRequests 99 Cosmos DB によってクライアントに対してレート制限が適用されたために要求が失敗した場合の最大再試行回数。The maximum number of retries if the request fails because Cosmos DB applied rate limiting on the client.
MaxRetryWaitTimeInSecondsMaxRetryWaitTimeInSeconds 3030 再試行の最大待機時間 (秒)。The maximum retry time in seconds.

Example

DocumentClient client = new DocumentClient(new Uri(endpoint), authKey); ;
var options = client.ConnectionPolicy.RetryOptions;
options.MaxRetryAttemptsOnThrottledRequests = 5;
options.MaxRetryWaitTimeInSeconds = 15;

テレメトリTelemetry

再試行回数は、.NET TraceSourceにより、構造化されていないトレース メッセージとしてログに記録されます。Retry attempts are logged as unstructured trace messages through a .NET TraceSource. イベントをキャプチャし、それらを適切な宛先ログに書き込むには、TraceListener を構成する必要があります。You must configure a TraceListener to capture the events and write them to a suitable destination log.

たとえば、次のコードを App.config ファイルに追加すると、同じ場所のテキスト ファイルに、実行可能ファイルとしてトレースが生成されます。For example, if you add the following to your App.config file, traces will be generated in a text file in the same location as the executable:

<configuration>
  <system.diagnostics>
    <switches>
      <add name="SourceSwitch" value="Verbose"/>
    </switches>
    <sources>
      <source name="DocDBTrace" switchName="SourceSwitch" switchType="System.Diagnostics.SourceSwitch" >
        <listeners>
          <add name="MyTextListener" type="System.Diagnostics.TextWriterTraceListener" traceOutputOptions="DateTime,ProcessId,ThreadId" initializeData="CosmosDBTrace.txt"></add>
        </listeners>
      </source>
    </sources>
  </system.diagnostics>
</configuration>

Event HubsEvent Hubs

Azure Event Hubs は、数百万のイベントを収集、変換、保存する、ハイパースケールのテレメトリ インジェスト サービスです。Azure Event Hubs is a hyperscale telemetry ingestion service that collects, transforms, and stores millions of events.

再試行メカニズムRetry mechanism

Azure Event Hubs Client Library での再試行動作は、EventHubClient クラスの RetryPolicy プロパティによって制御されます。Retry behavior in the Azure Event Hubs Client Library is controlled by the RetryPolicy property on the EventHubClient class. 既定のポリシーでは、Azure Hub が一時 EventHubsException または OperationCanceledException を返したときに、指数バックオフで再試行します。The default policy retries with exponential backoff when Azure Event Hub returns a transient EventHubsException or an OperationCanceledException. Event Hubs の既定の再試行ポリシーでは、再試行回数は最大 9 回、指数バックオフ時間は最大 30 秒です。Default retry policy for Event Hubs is to retry up to 9 times with an exponential back-off time of up to 30 seconds .

Example

EventHubClient client = EventHubClient.CreateFromConnectionString("[event_hub_connection_string]");
client.RetryPolicy = RetryPolicy.Default;

詳細情報More information

Azure Event Hubs の .NET Standard クライアント ライブラリ.NET Standard client library for Azure Event Hubs

IoT HubIoT Hub

Azure IoT Hub は、デバイスを接続、監視、および管理して、モノのインターネット (IoT) アプリケーションを開発するためのサービスです。Azure IoT Hub is a service for connecting, monitoring, and managing devices to develop Internet of Things (IoT) applications.

再試行メカニズムRetry mechanism

Azure IoT device SDK では、ネットワーク、プロトコル、またはアプリケーションのエラーを検出できます。The Azure IoT device SDK can detect errors in the network, protocol, or application. エラーの種類に基づき、SDK によって、再試行する必要があるかどうかが判断されます。Based on the error type, the SDK checks whether a retry needs to be performed. "回復可能" なエラーの場合、SDK により、構成済み再試行ポリシーを使用して再試行が開始されます。If the error is recoverable, the SDK begins to retry using the configured retry policy.

既定の再試行ポリシーは "指数バックオフとランダム ジッター" ですが、これは構成することができます。The default retry policy is exponential back-off with random jitter, but it can be configured.

ポリシーの構成Policy configuration

ポリシーの構成は言語によって異なります。Policy configuration differs by language. 詳細については、IoT Hub 再試行ポリシーの構成に関するページをご覧ください。For more details, see IoT Hub retry policy configuration.

詳細情報More information

Azure Cache for RedisAzure Cache for Redis

Azure Cache for Redis は、一般的なオープン ソース Redis Cache に基づく、高速データ アクセスと低待機時間のキャッシュ サービスです。Azure Cache for Redis is a fast data access and low latency cache service based on the popular open-source Redis cache. これは安全で、Microsoft により管理されており、Azure の任意のアプリケーションからアクセスできます。It is secure, managed by Microsoft, and is accessible from any application in Azure.

このセクションのガイダンスは、StackExchange.Redis クライアントを使用したキャッシュへのアクセスに基づいています。The guidance in this section is based on using the StackExchange.Redis client to access the cache. 他の適切なクライアントのリストについては、Redis の Web サイトを参照してください。それらのクライアントは異なる再試行メカニズムを備えている可能性があります。A list of other suitable clients can be found on the Redis website, and these may have different retry mechanisms.

StackExchange.Redis クライアントは、1 つの接続で多重化を使用することに注意してください。Note that the StackExchange.Redis client uses multiplexing through a single connection. 推奨される使用法は、アプリケーションの起動時にこのクライアントのインスタンスを作成し、そのインスタンスをキャッシュに対するすべての操作に使用するというものです。The recommended usage is to create an instance of the client at application startup and use this instance for all operations against the cache. このため、キャッシュへの接続が行われるのは 1 回限りであることから、このセクションのすべてのガイダンスは、その初期接続の再試行ポリシーに関連するものとなっています—キャッシュにアクセスする各操作に対するものではありません。For this reason, the connection to the cache is made only once, and so all of the guidance in this section is related to the retry policy for this initial connection—and not for each operation that accesses the cache.

再試行メカニズムRetry mechanism

StackExchange.Redis クライアントは、以下を含む一連のオプションで構成される接続マネージャー クラスを使用します。The StackExchange.Redis client uses a connection manager class that is configured through a set of options, including:

  • ConnectRetryConnectRetry. キャッシュに対し失敗した接続を再試行する回数。The number of times a failed connection to the cache will be retried.
  • ReconnectRetryPolicyReconnectRetryPolicy. 使用する再試行戦略。The retry strategy to use.
  • ConnectTimeoutConnectTimeout. 最大待機時間 (ミリ秒)。The maximum waiting time in milliseconds.

ポリシーの構成Policy configuration

再試行ポリシーは、キャッシュに接続する前に、クライアントにオプションを設定することで、プログラムによって構成されます。Retry policies are configured programmatically by setting the options for the client before connecting to the cache. これは、ConfigurationOptions クラスのインスタンスを作成し、そのプロパティを設定し、それを Connect メソッドに渡すことによって実行できます。This can be done by creating an instance of the ConfigurationOptions class, populating its properties, and passing it to the Connect method.

組み込みクラスは、ランダム化された再試行間隔の線形 (一定) 遅延および指数バックオフをサポートします。The built-in classes support linear (constant) delay and exponential backoff with randomized retry intervals. IReconnectRetryPolicy インターフェイスを実装することによって、カスタムの再試行ポリシーを作成することもできます。You can also create a custom retry policy by implementing the IReconnectRetryPolicy interface.

次の例では、指数バックオフを使用して、再試行戦略を構成します。The following example configures a retry strategy using exponential backoff.

var deltaBackOffInMilliseconds = TimeSpan.FromSeconds(5).Milliseconds;
var maxDeltaBackOffInMilliseconds = TimeSpan.FromSeconds(20).Milliseconds;
var options = new ConfigurationOptions
{
    EndPoints = {"localhost"},
    ConnectRetry = 3,
    ReconnectRetryPolicy = new ExponentialRetry(deltaBackOffInMilliseconds, maxDeltaBackOffInMilliseconds),
    ConnectTimeout = 2000
};
ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(options, writer);

または、文字列としてオプションを指定して、それを Connect メソッドに渡すこともできます。Alternatively, you can specify the options as a string, and pass this to the Connect method. ReconnectRetryPolicy プロパティはコードを使用してのみ設定でき、この方法では設定できません。The ReconnectRetryPolicy property cannot be set this way, only through code.

var options = "localhost,connectRetry=3,connectTimeout=2000";
ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(options, writer);

キャッシュに接続する際に、オプションを直接指定することもできます。You can also specify options directly when you connect to the cache.

var conn = ConnectionMultiplexer.Connect("redis0:6380,redis1:6380,connectRetry=3");

詳細については、StackExchange.Redis のマニュアルの Stack Exchange Redis の構成を参照してください。For more information, see Stack Exchange Redis Configuration in the StackExchange.Redis documentation.

次の表は、組み込み再試行ポリシーの既定の設定を示しています。The following table shows the default settings for the built-in retry policy.

コンテキストContext 設定Setting 既定値Default value
(v 1.2.2)(v 1.2.2)
意味Meaning
構成オプションConfigurationOptions ConnectRetryConnectRetry

ConnectTimeoutConnectTimeout

SyncTimeoutSyncTimeout

ReconnectRetryPolicyReconnectRetryPolicy
33

最大 5,000 ミリ秒に SyncTimeout を加算Maximum 5000 ms plus SyncTimeout
10001000

LinearRetry 5000 ミリ秒LinearRetry 5000 ms
初期接続操作中に接続試行を繰り返す回数。The number of times to repeat connect attempts during the initial connection operation.
接続操作のタイムアウト (ミリ秒)。Timeout (ms) for connect operations. 再試行間の遅延ではありません。Not a delay between retry attempts.
同期操作が許容される時間 (ミリ秒)。Time (ms) to allow for synchronous operations.

5000 ミリ秒ごとに再試行してください。Retry every 5000 ms.

注意

同期操作では、SyncTimeout によりエンド ツー エンドの待機時間を追加できますが、設定値が低すぎると、過剰にタイムアウトが発生することがあります。For synchronous operations, SyncTimeout can add to the end-to-end latency, but setting the value too low can cause excessive timeouts. Azure Cache for Redis のトラブルシューティング方法」を参照してください。See How to troubleshoot Azure Cache for Redis. 一般に、同期操作ではなく、非同期操作を使用してください。In general, avoid using synchronous operations, and use asynchronous operations instead. 詳細については、「Pipelines and Multiplexers (パイプラインとマルチプレクサー)」を参照してください。For more information, see Pipelines and Multiplexers.

再試行使用のガイダンスRetry usage guidance

Azure Cache for Redis を使用する場合は、次のガイドラインについて検討します。Consider the following guidelines when using Azure Cache for Redis:

  • StackExchange Redis クライアントは、その独自の再試行を管理します。ただし、アプリケーションの初回の起動時にキャッシュへの接続を確立するときのみです。The StackExchange Redis client manages its own retries, but only when establishing a connection to the cache when the application first starts. 接続タイムアウト、再試行回数、接続の再試行間の間隔を設定できますが、キャッシュに対する操作には再試行ポリシーは適用されません。You can configure the connection timeout, the number of retry attempts, and the time between retries to establish this connection, but the retry policy does not apply to operations against the cache.
  • 多数の再試行を使用するのではなく、元のデータ ソースにアクセスすることによってフォールバックすることを検討してください。Instead of using a large number of retry attempts, consider falling back by accessing the original data source instead.

テレメトリTelemetry

接続 (他の操作ではない) に関する情報は、 TextWriterを使用して収集できます。You can collect information about connections (but not other operations) using a TextWriter.

var writer = new StringWriter();
ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(options, writer);

これが生成する出力の例を次に示します。An example of the output this generates is shown below.

localhost:6379,connectTimeout=2000,connectRetry=3
1 unique nodes specified
Requesting tie-break from localhost:6379 > __Booksleeve_TieBreak...
Allowing endpoints 00:00:02 to respond...
localhost:6379 faulted: SocketFailure on PING
localhost:6379 failed to nominate (Faulted)
> UnableToResolvePhysicalConnection on GET
No masters detected
localhost:6379: Standalone v2.0.0, master; keep-alive: 00:01:00; int: Connecting; sub: Connecting; not in use: DidNotRespond
localhost:6379: int ops=0, qu=0, qs=0, qc=1, wr=0, sync=1, socks=2; sub ops=0, qu=0, qs=0, qc=0, wr=0, socks=2
Circular op-count snapshot; int: 0 (0.00 ops/s; spans 10s); sub: 0 (0.00 ops/s; spans 10s)
Sync timeouts: 0; fire and forget: 0; last heartbeat: -1s ago
resetting failing connections to retry...
retrying; attempts left: 2...
...

Examples

次のコード例では、StackExchange.Redis クライアントを初期化する際に、再試行と再試行の間の一定 (線形) の待ち時間を構成します。The following code example configures a constant (linear) delay between retries when initializing the StackExchange.Redis client. この例は、ConfigurationOptions のインスタンスを使用して構成を設定する方法を示しています。This example shows how to set the configuration using a ConfigurationOptions instance.

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using StackExchange.Redis;

namespace RetryCodeSamples
{
    class CacheRedisCodeSamples
    {
        public async static Task Samples()
        {
            var writer = new StringWriter();
            {
                try
                {
                    var retryTimeInMilliseconds = TimeSpan.FromSeconds(4).Milliseconds; // delay between retries

                    // Using object-based configuration.
                    var options = new ConfigurationOptions
                                        {
                                            EndPoints = { "localhost" },
                                            ConnectRetry = 3,
                                            ReconnectRetryPolicy = new LinearRetry(retryTimeInMilliseconds)
                                        };
                    ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(options, writer);

                    // Store a reference to the multiplexer for use in the application.
                }
                catch
                {
                    Console.WriteLine(writer.ToString());
                    throw;
                }
            }
        }
    }
}

次の例では、オプションを文字列として指定することで、構成を設定しています。The next example sets the configuration by specifying the options as a string. 接続タイムアウトとは、キャッシュへの接続での最大待ち期間であり、再試行間の待ち時間ではありません。The connection timeout is the maximum period of time to wait for a connection to the cache, not the delay between retry attempts. なお、ReconnectRetryPolicy プロパティは、コードを使用してのみ設定できます。Note that the ReconnectRetryPolicy property can only be set by code.

using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using StackExchange.Redis;

namespace RetryCodeSamples
{
    class CacheRedisCodeSamples
    {
        public async static Task Samples()
        {
            var writer = new StringWriter();
            {
                try
                {
                    // Using string-based configuration.
                    var options = "localhost,connectRetry=3,connectTimeout=2000";
                    ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(options, writer);

                    // Store a reference to the multiplexer for use in the application.
                }
                catch
                {
                    Console.WriteLine(writer.ToString());
                    throw;
                }
            }
        }
    }
}

詳細な例については、プロジェクト Web サイトの「Configuration (構成)」を参照してください。For more examples, see Configuration on the project website.

詳細情報More information

Azure Search は、Web サイトまたはアプリケーションへの強力で高度な検索機能の追加、検索結果のすばやく簡単な調整、および微調整された豊富な順位付けモデルの構築を行うために使用できます。Azure Search can be used to add powerful and sophisticated search capabilities to a website or application, quickly and easily tune search results, and construct rich and fine-tuned ranking models.

再試行メカニズムRetry mechanism

Azure Search SDK の再試行動作は、SearchServiceClient クラスと SearchIndexClient クラスの SetRetryPolicy メソッドで制御されます。Retry behavior in the Azure Search SDK is controlled by the SetRetryPolicy method on the SearchServiceClient and SearchIndexClient classes. 既定のポリシーでは、Azure Search から 5xx または 408 (要求タイムアウト) の応答が返された場合に、指数関数的バックオフによる再試行が行われます。The default policy retries with exponential backoff when Azure Search returns a 5xx or 408 (Request Timeout) response.

テレメトリTelemetry

ETW を使用してトレースするか、カスタム トレース プロバイダーを登録してトレースします。Trace with ETW or by registering a custom trace provider. 詳細については、AutoRest のドキュメントを参照してください。For more information, see the AutoRest documentation.

Service BusService Bus

Service Bus は、クラウド メッセージング プラットフォームであり、クラウドまたはオンプレミスでホストされているアプリケーションのコンポーネントに対して、向上したスケーラビリティと回復性を備えた疎結合のメッセージ交換を提供します。Service Bus is a cloud messaging platform that provides loosely coupled message exchange with improved scale and resiliency for components of an application, whether hosted in the cloud or on-premises.

再試行メカニズムRetry mechanism

Service Bus は、RetryPolicy 抽象クラスの実装を使用して、再試行を実装します。Service Bus implements retries using implementations of the abstract RetryPolicy class. 名前空間と一部の構成の詳細は、使用されている Service Bus クライアント SDK パッケージによって異なります。The namespace and some of the configuration details depend on which Service Bus client SDK package is used:

PackagePackage 説明Description 名前空間Namespace
Microsoft.Azure.ServiceBusMicrosoft.Azure.ServiceBus .NET Standard 用の Azure Service Bus クライアント ライブラリ。Azure Service Bus client library for .NET Standard. Microsoft.ServiceBus
WindowsAzure.ServiceBusWindowsAzure.ServiceBus このパッケージは、以前の Service Bus クライアントライブラリです。This package is the older Service Bus client library. これには .Net Framework 4.5.2 が必要です。It requires .Net Framework 4.5.2. Microsoft.Azure.ServiceBus

どちらのバージョンのクライアント ライブラリにも、次の RetryPolicy 組み込み実装が用意されています。Both versions of the client library provide the following built-in implementations of RetryPolicy:

  • RetryExponentialRetryExponential. エクスポネンシャル バックオフが実装されています。Implements exponential backoff.

  • NoRetryNoRetry. 再試行は実行されません。Does not perform retries. このクラスは、Service Bus API レベルでの再試行が不要な場合、たとえば、再試行がバッチまたは複数ステップ操作の一部として他のプロセスによって管理されている場合に使用します。Use this class when you don't need retries at the Service Bus API level, for example when another process manages retries as part of a batch or multistep operation.

RetryPolicy.Default プロパティによって、型 RetryExponential の既定のポリシーが返されます。The RetryPolicy.Default property returns a default policy of type RetryExponential. このポリシー オブジェクトには、次の設定があります。This policy object has the following settings:

設定Setting 既定値Default value 意味Meaning
MinimalBackoffMinimalBackoff 00 最小バックオフ間隔。Minimum back-off interval. deltaBackoff から計算された再試行間隔に追加されます。Added to the retry interval computed from deltaBackoff.
MaximumBackoffMaximumBackoff 30 秒30 seconds 最大バックオフ間隔。Maximum back-off interval.
DeltaBackoffDeltaBackoff 3 秒3 seconds 再試行のバックオフ間隔。Back-off interval between retries. この期間の倍数は、後続の再試行に使用されます。Multiples of this timespan are used for subsequent retry attempts.
MaxRetryCountMaxRetryCount 55 最大再試行回数。The maximum number of retries. (WindowsAzure.ServiceBus パッケージでは既定値は 10。)(Default value is 10 in the WindowsAzure.ServiceBus package.)

さらに、古い WindowsAzure.ServiceBus パッケージでは次のプロパティが定義されています。In addition, the following property is defined in the older WindowsAzure.ServiceBus package:

設定Setting 既定値Default value 意味Meaning
TerminationTimeBufferTerminationTimeBuffer 5 秒5 seconds 残り時間がこの値を下回ると再試行は中止されます。Retry attempts will be abandoned if the remaining time is less than this value.

Service Bus のアクションにより、さまざまな例外 (「Service Bus メッセージングの例外」を参照) が返される可能性があります。Service Bus actions can return a range of exceptions, listed in Service Bus messaging exceptions. Service Bus から返される例外は IsTransient プロパティを公開し、これはクライアントが操作を再試行するかどうかを示します。Exceptions returned from Service Bus expose the IsTransient property that indicates whether the client should retry the operation. このプロパティは、組み込みの RetryExponential ポリシーによって再試行前に確認されます。The built-in RetryExponential policy checks this property before retrying.

検出された最後の例外が ServerBusyException の場合、RetryExponential ポリシーによって、計算された再試行間隔に 10 秒が追加されます。If the last exception encountered was ServerBusyException, the RetryExponential policy adds 10 seconds to the computed retry interval. この値は変更できません。This value cannot be changed.

カスタム実装では、例外タイプと IsTransient プロパティの組み合わせを使用して、再試行アクションをより細かく制御することができます。Custom implementations could use a combination of the exception type and the IsTransient property to provide more fine-grained control over retry actions. たとえば、 QuotaExceededException を検出した場合に、キューへのメッセージの送信を再試行する前に、キューを排出するアクションを実行することができます。For example, you could detect a QuotaExceededException and take action to drain the queue before retrying sending a message to it.

次のコードは、Microsoft.Azure.ServiceBus ライブラリを使用して、Service Bus クライアントの再試行ポリシーを設定します。The following code sets the retry policy on a Service Bus client using the Microsoft.Azure.ServiceBus library:

const string QueueName = "queue1";
const string ServiceBusConnectionString = "<your_connection_string>";

var policy = new RetryExponential(
    minimumBackoff: TimeSpan.FromSeconds(10),
    maximumBackoff: TimeSpan.FromSeconds(30),
    maximumRetryCount: 3);
var queueClient = new QueueClient(ServiceBusConnectionString, QueueName, ReceiveMode.PeekLock, policy);

再試行ポリシーは、個々の操作レベルで設定することはできません。The retry policy cannot be set at the individual operation level. これはクライアントのすべての操作に適用されます。It applies to all operations for the client.

再試行使用のガイダンスRetry usage guidance

Service Bus を使用する場合は、次のガイドラインについて検討します。Consider the following guidelines when using Service Bus:

  • 組み込みの RetryExponential 実装を使用する際には、ポリシーがサーバー ビジー例外に反応し、適切な再試行モードに自動的に切り替えるので、フォールバック操作を実装しないでください。When using the built-in RetryExponential implementation, do not implement a fallback operation as the policy reacts to Server Busy exceptions and automatically switches to an appropriate retry mode.
  • Service Bus は、組み合わせ名前空間という機能をサポートします。これは、プライマリ名前空間内のキューでエラーが発生した場合の、別の名前空間内にあるバックアップ キューへの自動フェールオーバーを実装します。Service Bus supports a feature called Paired Namespaces that implements automatic failover to a backup queue in a separate namespace if the queue in the primary namespace fails. セカンダリ キューからのメッセージは、プライマリ キューが回復したらそこに送り戻すことができます。Messages from the secondary queue can be sent back to the primary queue when it recovers. この機能は、一時的なエラーに対処するために役立ちます。This feature helps to address transient failures. 詳細については、「非同期メッセージング パターンと高可用性」を参照してください。For more information, see Asynchronous Messaging Patterns and High Availability.

再試行操作を次の設定から始めることを検討してください。Consider starting with the following settings for retrying operations. これらの設定は汎用であり、操作を監視して、独自のシナリオに合うように値を微調整する必要があります。These settings are general purpose, and you should monitor the operations and fine-tune the values to suit your own scenario.

ContextContext 最大待機時間の例Example maximum latency 再試行ポリシーRetry policy 設定Settings しくみHow it works
対話型、UI、またはフォアグラウンドInteractive, UI, or foreground 2 秒*2 seconds* 指数Exponential MinimumBackoff = 0MinimumBackoff = 0
MaximumBackoff = 30 秒MaximumBackoff = 30 sec.
DeltaBackoff = 300 ミリ秒DeltaBackoff = 300 msec.
TimeBuffer = 300 ミリ秒TimeBuffer = 300 msec.
MaxRetryCount = 2MaxRetryCount = 2
試行 1: 0 秒の遅延Attempt 1: Delay 0 sec.
試行 2: 最大 300 ミリ秒の遅延Attempt 2: Delay ~300 msec.
試行 3: 最大 900 ミリ秒の遅延Attempt 3: Delay ~900 msec.
バックグラウンドまたはバッチBackground or batch 30 秒30 seconds 指数Exponential MinimumBackoff = 1MinimumBackoff = 1
MaximumBackoff = 30 秒MaximumBackoff = 30 sec.
DeltaBackoff = 1.75 秒DeltaBackoff = 1.75 sec.
TimeBuffer = 5 秒TimeBuffer = 5 sec.
MaxRetryCount = 3MaxRetryCount = 3
試行 1: 最大 1 秒の遅延Attempt 1: Delay ~1 sec.
試行 2: 最大 3 秒の遅延Attempt 2: Delay ~3 sec.
試行 3: 最大 6 ミリ秒の遅延Attempt 3: Delay ~6 msec.
試行 4: 最大 13 ミリ秒の遅延Attempt 4: Delay ~13 msec.

* サーバー ビジー応答を受信した場合に追加される遅延は含まれません。* Not including additional delay that is added if a Server Busy response is received.

テレメトリTelemetry

Service Bus は、再試行を ETW イベントとして EventSourceを使ってログに記録します。Service Bus logs retries as ETW events using an EventSource. イベントをキャプチャしてパフォーマンス ビューアーに表示したり、イベントを適切な宛先ログに書き込んだりするには、 EventListener をイベント ソースにアタッチする必要があります。You must attach an EventListener to the event source to capture the events and view them in Performance Viewer, or write them to a suitable destination log. 再試行イベントは、次の形式です。The retry events are of the following form:

Microsoft-ServiceBus-Client/RetryPolicyIteration
ThreadID="14,500"
FormattedMessage="[TrackingId:] RetryExponential: Operation Get:https://retry-tests.servicebus.windows.net/TestQueue/?api-version=2014-05 at iteration 0 is retrying after 00:00:00.1000000 sleep because of Microsoft.ServiceBus.Messaging.MessagingCommunicationException: The remote name could not be resolved: 'retry-tests.servicebus.windows.net'.TrackingId:6a26f99c-dc6d-422e-8565-f89fdd0d4fe3, TimeStamp:9/5/2014 10:00:13 PM."
trackingId=""
policyType="RetryExponential"
operation="Get:https://retry-tests.servicebus.windows.net/TestQueue/?api-version=2014-05"
iteration="0"
iterationSleep="00:00:00.1000000"
lastExceptionType="Microsoft.ServiceBus.Messaging.MessagingCommunicationException"
exceptionMessage="The remote name could not be resolved: 'retry-tests.servicebus.windows.net'.TrackingId:6a26f99c-dc6d-422e-8565-f89fdd0d4fe3,TimeStamp:9/5/2014 10:00:13 PM"

Examples

次のコード例は、以下に対する再試行ポリシーの設定方法を示しています。The following code example shows how to set the retry policy for:

  • 名前空間マネージャー。A namespace manager. ポリシーは、そのマネージャー上のすべての操作に適用されます。個々の操作向けにオーバーライドすることはできません。The policy applies to all operations on that manager, and cannot be overridden for individual operations.
  • メッセージング ファクトリ。A messaging factory. ポリシーは、このファクトリから作成されたすべてのクライアントに適用されます。個々のクライアントの作成時にオーバーライドすることはできません。The policy applies to all clients created from that factory, and cannot be overridden when creating individual clients.
  • 個々のメッセージング クライアントAn individual messaging client. クライアントの作成後に、そのクライアントに再試行ポリシーを設定することができます。After a client has been created, you can set the retry policy for that client. ポリシーは、そのクライアント上のすべての操作に適用されます。The policy applies to all operations on that client.
using System;
using System.Threading.Tasks;
using Microsoft.ServiceBus;
using Microsoft.ServiceBus.Messaging;

namespace RetryCodeSamples
{
    class ServiceBusCodeSamples
    {
        private const string connectionString =
            @"Endpoint=sb://[my-namespace].servicebus.windows.net/;
                SharedAccessKeyName=RootManageSharedAccessKey;
                SharedAccessKey=C99..........Mk=";

        public async static Task Samples()
        {
            const string QueueName = "TestQueue";

            ServiceBusEnvironment.SystemConnectivity.Mode = ConnectivityMode.Http;

            var namespaceManager = NamespaceManager.CreateFromConnectionString(connectionString);

            // The namespace manager will have a default exponential policy with 10 retry attempts
            // and a 3 second delay delta.
            // Retry delays will be approximately 0 sec, 3 sec, 9 sec, 25 sec and the fixed 30 sec,
            // with an extra 10 sec added when receiving a ServiceBusyException.

            {
                // Set different values for the retry policy, used for all operations on the namespace manager.
                namespaceManager.Settings.RetryPolicy =
                    new RetryExponential(
                        minBackoff: TimeSpan.FromSeconds(0),
                        maxBackoff: TimeSpan.FromSeconds(30),
                        maxRetryCount: 3);

                // Policies cannot be specified on a per-operation basis.
                if (!await namespaceManager.QueueExistsAsync(QueueName))
                {
                    await namespaceManager.CreateQueueAsync(QueueName);
                }
            }

            var messagingFactory = MessagingFactory.Create(
                namespaceManager.Address, namespaceManager.Settings.TokenProvider);
            // The messaging factory will have a default exponential policy with 10 retry attempts
            // and a 3 second delay delta.
            // Retry delays will be approximately 0 sec, 3 sec, 9 sec, 25 sec and the fixed 30 sec,
            // with an extra 10 sec added when receiving a ServiceBusyException.

            {
                // Set different values for the retry policy, used for clients created from it.
                messagingFactory.RetryPolicy =
                    new RetryExponential(
                        minBackoff: TimeSpan.FromSeconds(1),
                        maxBackoff: TimeSpan.FromSeconds(30),
                        maxRetryCount: 3);


                // Policies cannot be specified on a per-operation basis.
                var session = await messagingFactory.AcceptMessageSessionAsync();
            }

            {
                var client = messagingFactory.CreateQueueClient(QueueName);
                // The client inherits the policy from the factory that created it.


                // Set different values for the retry policy on the client.
                client.RetryPolicy =
                    new RetryExponential(
                        minBackoff: TimeSpan.FromSeconds(0.1),
                        maxBackoff: TimeSpan.FromSeconds(30),
                        maxRetryCount: 3);

                // Policies cannot be specified on a per-operation basis.
                var session = await client.AcceptMessageSessionAsync();
            }
        }
    }
}

詳細情報More information

Service FabricService Fabric

Service Fabric クラスターで信頼性の高いサービスを配信することにより、この記事に記載されているほぼすべての潜在的な一時障害を防止できます。Distributing reliable services in a Service Fabric cluster guards against most of the potential transient faults discussed in this article. ただ、それでも一部の一時障害は発生します。Some transient faults are still possible, however. たとえば、名前付けサービスでルーティングを変更中に要求を受信すると例外がスローされます。For example, the naming service might be in the middle of a routing change when it gets a request, causing it to throw an exception. 同じ要求を 100 ミリ秒後に受信すると、要求は成功する可能性が高くなります。If the same request comes 100 milliseconds later, it will probably succeed.

内部的には、Service Fabric が、この種の一時的な障害を管理します。Internally, Service Fabric manages this kind of transient fault. サービスのセットアップ時に、クラス OperationRetrySettings を使用して一部の設定を構成することができます。You can configure some settings by using the OperationRetrySettings class while setting up your services. 次のコードは例を示します。The following code shows an example. ほとんどの場合、既定の設定で対応できるため、このコードは必要ありません。In most cases, this should not be necessary, and the default settings will be fine.

FabricTransportRemotingSettings transportSettings = new FabricTransportRemotingSettings
{
    OperationTimeout = TimeSpan.FromSeconds(30)
};

var retrySettings = new OperationRetrySettings(TimeSpan.FromSeconds(15), TimeSpan.FromSeconds(1), 5);

var clientFactory = new FabricTransportServiceRemotingClientFactory(transportSettings);

var serviceProxyFactory = new ServiceProxyFactory((c) => clientFactory, retrySettings);

var client = serviceProxyFactory.CreateServiceProxy<ISomeService>(
    new Uri("fabric:/SomeApp/SomeStatefulReliableService"),
    new ServicePartitionKey(0));

詳細情報More information

ADO.NET を使用した SQL Database アクセスSQL Database using ADO.NET

SQL Database は、多様なサイズで利用できるホステッド SQL データベースです。これは Standard (共有) サービスと Premium (非共有) サービスのどちらとしてでも使用できます。SQL Database is a hosted SQL database available in a range of sizes and as both a standard (shared) and premium (non-shared) service.

再試行メカニズムRetry mechanism

ADO.NET を使用してアクセスする際には、SQL Database には再試行の組み込みサポートはありません。SQL Database has no built-in support for retries when accessed using ADO.NET. ただし、要求からのリターン コードを使用して、要求が失敗した理由を判別することができます。However, the return codes from requests can be used to determine why a request failed. SQL Database の調整の詳細については、「Azure SQL データベースのリソース制限」を参照してください。For more information about SQL Database throttling, see Azure SQL Database resource limits. 関連するエラー コードの一覧については、「SQL Database クライアント アプリケーションの SQL エラー コード」を参照してください。For a list of relevant error codes, see SQL error codes for SQL Database client applications.

SQL Database の再試行は、Polly ライブラリを使用して実装できます。You can use the Polly library to implement retries for SQL Database. Polly での一時的な障害処理を参照してください。See Transient fault handling with Polly.

再試行使用のガイダンスRetry usage guidance

ADO.NET を使用して SQL Database にアクセスする場合は、次のガイドラインを検討します。Consider the following guidelines when accessing SQL Database using ADO.NET:

  • 適切なサービス オプション (Shared または Premium) を選択します。Choose the appropriate service option (shared or premium). 共有インスタンスは、共有サーバーの他のテナントによる使用状況により、通常よりも長い接続遅延や調整の影響を受ける可能性があります。A shared instance may suffer longer than usual connection delays and throttling due to the usage by other tenants of the shared server. 予測可能性の高いパフォーマンスと信頼性の高い低待機時間での操作が必要な場合は、Premium オプションを選択することを検討してください。If more predictable performance and reliable low latency operations are required, consider choosing the premium option.
  • データの不整合の原因となる非べき等操作を避けるために、再試行は必ず適切なレベルまたはスコープで実行します。Ensure that you perform retries at the appropriate level or scope to avoid non-idempotent operations causing inconsistency in the data. 理想的には、すべての操作はべき等にして、不整合を発生させずに繰り返し実行できるようにする必要があります。Ideally, all operations should be idempotent so that they can be repeated without causing inconsistency. これが当てはまらない場合、再試行は、操作が失敗した場合に、関連するすべての変更を元に戻すことができるレベルまたはスコープで (たとえば 1 トランザクションのスコープ内で) 実行する必要があります。Where this is not the case, the retry should be performed at a level or scope that allows all related changes to be undone if one operation fails; for example, from within a transactional scope. 詳細については、「Cloud Service Fundamentals Data Access Layer – Transient Fault Handling (クラウド サービスの基本データ アクセス層 – 一時的エラー処理)」を参照してください。For more information, see Cloud Service Fundamentals Data Access Layer – Transient Fault Handling.
  • 固定間隔戦略は、非常に短い間隔でごくわずかな回数の再試行が実行されるのみという対話型のシナリオを除き、Azure SQL Database での使用は推奨されていません。A fixed interval strategy is not recommended for use with Azure SQL Database except for interactive scenarios where there are only a few retries at very short intervals. 代わりに、ほとんどのシナリオで、指数バックオフ戦略を使用することを考慮してください。Instead, consider using an exponential back-off strategy for the majority of scenarios.
  • 接続を定義するときは、接続タイムアウトとコマンド タイムアウトに適切な値を選択します。Choose a suitable value for the connection and command timeouts when defining connections. タイムアウトが短すぎると、データベースがビジー状態の場合に、接続が途中でエラーになる可能性があります。Too short a timeout may result in premature failures of connections when the database is busy. タイムアウトが長すぎると、接続エラーを検出するまで長く待ちすぎて、再試行ロジックが正常に機能しなくなる可能性があります。Too long a timeout may prevent the retry logic working correctly by waiting too long before detecting a failed connection. タイムアウトの値は、エンドツーエンド待機時間の構成要素です。これはすべての再試行向けの再試行ポリシーに指定される再試行遅延に、事実上追加されます。The value of the timeout is a component of the end-to-end latency; it is effectively added to the retry delay specified in the retry policy for every retry attempt.
  • 指数バックオフ再試行ロジックを使用している場合でも、一定回数の再試行が実行された後は接続を閉じ、新しい接続で操作を再試行します。Close the connection after a certain number of retries, even when using an exponential back off retry logic, and retry the operation on a new connection. 同じ接続で同じ操作を複数回再試行することは、接続問題を生じさせる要因となる場合があります。Retrying the same operation multiple times on the same connection can be a factor that contributes to connection problems. この技法の例については、「Cloud Service Fundamentals Data Access Layer – Transient Fault Handling (クラウド サービスの基本データ アクセス層 – 一時的エラー処理)」を参照してください。For an example of this technique, see Cloud Service Fundamentals Data Access Layer – Transient Fault Handling.
  • 接続プールが使用中であれば (既定値)、接続を閉じてから再び開いた後であっても、同じ接続がプールから選択される可能性があります。When connection pooling is in use (the default) there is a chance that the same connection will be chosen from the pool, even after closing and reopening a connection. これが該当する場合、解決するための技法は、SqlConnection クラスの ClearPool メソッドを呼び出して、接続を再利用不可とマークすることです。If this is the case, a technique to resolve it is to call the ClearPool method of the SqlConnection class to mark the connection as not reusable. ただし、これは数回の接続試行が失敗し、問題がある接続に関連した SQL タイムアウト (エラー コード -2) などの、特定クラスの一時的エラーを検出した場合にのみ実行してください。However, you should do this only after several connection attempts have failed, and only when encountering the specific class of transient failures such as SQL timeouts (error code -2) related to faulty connections.
  • データ アクセス コードが TransactionScope インスタンスとして開始されたトランザクションを使用している場合、再試行ロジックは接続を再度開き、新しいトランザクション スコープを開始する必要があります。If the data access code uses transactions initiated as TransactionScope instances, the retry logic should reopen the connection and initiate a new transaction scope. この理由から、再試行可能コード ブロックは、トランザクションのスコープ全体をカバーしている必要があります。For this reason, the retryable code block should encompass the entire scope of the transaction.

再試行操作を次の設定から始めることを検討してください。Consider starting with the following settings for retrying operations. これらの設定は汎用であり、操作を監視して、独自のシナリオに合うように値を微調整する必要があります。These settings are general purpose, and you should monitor the operations and fine-tune the values to suit your own scenario.

コンテキストContext サンプルのターゲット E2E
最大待機時間
Sample target E2E
max latency
再試行戦略Retry strategy 設定Settings Values 動作のしくみHow it works
対話型、UI、Interactive, UI,
またはフォアグラウンドor foreground
2 秒2 sec FixedIntervalFixedInterval 再試行回数Retry count
再試行間隔Retry interval
最初の高速再試行First fast retry
33
500 ミリ秒500 ms
truetrue
試行 1 - 0 秒の遅延Attempt 1 - delay 0 sec
試行 2 - 500 ミリ秒の遅延Attempt 2 - delay 500 ms
試行 3 - 500 ミリ秒の遅延Attempt 3 - delay 500 ms
バックグラウンドBackground
またはバッチor batch
30 秒30 sec ExponentialBackoffExponentialBackoff 再試行回数Retry count
最小バックオフMin back-off
最大バックオフMax back-off
差分バックオフDelta back-off
最初の高速再試行First fast retry
55
0 秒0 sec
60 秒60 sec
2 秒2 sec
falsefalse
試行 1 - 0 秒の遅延Attempt 1 - delay 0 sec
試行 2 - 最大 2 秒の遅延Attempt 2 - delay ~2 sec
試行 3 - 最大 6 秒の遅延Attempt 3 - delay ~6 sec
試行 4 - 最大 14 秒の遅延Attempt 4 - delay ~14 sec
試行 5 - 最大 30 秒の遅延Attempt 5 - delay ~30 sec

注意

エンドツーエンド待機時間のターゲットには、サービスへの接続用の既定のタイムアウトが想定されます。The end-to-end latency targets assume the default timeout for connections to the service. 接続タイムアウトにより長い時間を指定する場合、エンドツーエンド待機時間は、すべての再試行についてこの追加時間分だけ延長されます。If you specify longer connection timeouts, the end-to-end latency will be extended by this additional time for every retry attempt.

Examples

このセクションでは、Polly を使用して、Policy クラスに構成されている再試行ポリシーを使用して Azure SQL Database にアクセスする方法について説明します。This section shows how you can use Polly to access Azure SQL Database using a set of retry policies configured in the Policy class.

次のコードは、指数バックオフを使用して ExecuteAsync を呼び出す、SqlCommand クラスの拡張メソッドを示しています。The following code shows an extension method on the SqlCommand class that calls ExecuteAsync with exponential backoff.

public async static Task<SqlDataReader> ExecuteReaderWithRetryAsync(this SqlCommand command)
{
    GuardConnectionIsNotNull(command);

    var policy = Policy.Handle<Exception>().WaitAndRetryAsync(
        retryCount: 3, // Retry 3 times
        sleepDurationProvider: attempt => TimeSpan.FromMilliseconds(200 * Math.Pow(2, attempt - 1)), // Exponential backoff based on an initial 200 ms delay.
        onRetry: (exception, attempt) =>
        {
            // Capture some information for logging/telemetry.
            logger.LogWarn($"ExecuteReaderWithRetryAsync: Retry {attempt} due to {exception}.");
        });

    // Retry the following call according to the policy.
    await policy.ExecuteAsync<SqlDataReader>(async token =>
    {
        // This code is executed within the Policy

        if (conn.State != System.Data.ConnectionState.Open) await conn.OpenAsync(token);
        return await command.ExecuteReaderAsync(System.Data.CommandBehavior.Default, token);

    }, cancellationToken);
}

この非同期の拡張メソッドは、次のように使用できます。This asynchronous extension method can be used as follows.

var sqlCommand = sqlConnection.CreateCommand();
sqlCommand.CommandText = "[some query]";

using (var reader = await sqlCommand.ExecuteReaderWithRetryAsync())
{
    // Do something with the values
}

詳細情報More information

SQL Database を最大限活用するための一般的なガイダンスについては、Azure SQL Database パフォーマンス/弾力性に関するガイドを参照してください。For general guidance on getting the most from SQL Database, see Azure SQL Database performance and elasticity guide.

Entity Framework 6 を使用した SQL Database アクセスSQL Database using Entity Framework 6

SQL Database は、多様なサイズで利用できるホステッド SQL データベースです。これは Standard (共有) サービスと Premium (非共有) サービスのどちらとしてでも使用できます。SQL Database is a hosted SQL database available in a range of sizes and as both a standard (shared) and premium (non-shared) service. Entity Framework は、.NET 開発者がドメイン固有オブジェクトを使用してリレーショナル データを操作できるようにする、オブジェクトリレーショナル マッパーです。Entity Framework is an object-relational mapper that enables .NET developers to work with relational data using domain-specific objects. これにより、開発者が通常は記述する必要のあるデータアクセス コードの大部分が不要になります。It eliminates the need for most of the data-access code that developers usually need to write.

再試行メカニズムRetry mechanism

再試行サポートは、SQL Database データベースに、Entity Framework 6.0 以降で接続回復/再試行ロジックというメカニズムを用いてアクセスするときに提供されます。Retry support is provided when accessing SQL Database using Entity Framework 6.0 and higher through a mechanism called Connection resiliency / retry logic. 再試行メカニズムの主な機能は、次のとおりです。The main features of the retry mechanism are:

  • 主要な抽象化は、 IDbExecutionStrategy インターフェイスです。The primary abstraction is the IDbExecutionStrategy interface. このインターフェイスは、次の事柄を実行します。This interface:
    • 同期および非同期の Execute メソッドを定義します。Defines synchronous and asynchronous Execute methods.
    • 既定の戦略として、直接使用できるクラス、またはデータベース コンテキストに基づいて構成できるクラスを定義します。このクラスは、プロバイダー名にマップされるかまたはプロバイダー名とサーバー名にマップされます。Defines classes that can be used directly or can be configured on a database context as a default strategy, mapped to provider name, or mapped to a provider name and server name. コンテキストに基づいて構成された場合、再試行は個々のデータベース操作のレベルで行われます。特定の 1 コンテキスト操作に対して複数の再試行が行われる場合もあります。When configured on a context, retries occur at the level of individual database operations, of which there might be several for a given context operation.
    • 失敗した接続をいつ、どのように再試行するかを定義します。Defines when to retry a failed connection, and how.
  • これには、 IDbExecutionStrategy インターフェイスの次のいくつかの組み込み実装が含まれます。It includes several built-in implementations of the IDbExecutionStrategy interface:
    • 既定値: 再試行なし。Default: no retrying.
    • SQL Database の既定値 (自動): 再試行なし。ただし例外を検査し、SQL Database 戦略を使用するという提案でそれらをラップします。Default for SQL Database (automatic): no retrying, but inspects exceptions and wraps them with suggestion to use the SQL Database strategy.
    • SQL Database の既定値: Exponential (基本クラスからの継承) に、SQL Database の検出ロジックを加えたもの。Default for SQL Database: exponential (inherited from base class) plus SQL Database detection logic.
  • ランダム化を含む指数バックオフ戦略を実装します。It implements an exponential back-off strategy that includes randomization.
  • 組み込み再試行クラスは、ステートフルですが、スレッドセーフではありません。The built-in retry classes are stateful and are not thread-safe. ただし、このクラスは現在の操作が完了した後に再利用できます。However, they can be reused after the current operation is completed.
  • 指定した再試行回数を超えた場合、結果は新しい例外でラップされます。If the specified retry count is exceeded, the results are wrapped in a new exception. これは現在の例外をバブルアップしません。It does not bubble up the current exception.

ポリシーの構成Policy configuration

再試行サポートは、Entity Framework 6.0 以降を使用して SQL Database にアクセスする場合に提供されます。Retry support is provided when accessing SQL Database using Entity Framework 6.0 and higher. 再試行ポリシーは、プログラムにより構成されます。Retry policies are configured programmatically. 構成を操作ごとに変更することはできません。The configuration cannot be changed on a per-operation basis.

コンテキストに基づいて既定値として戦略を構成する場合は、新しい戦略をオンデマンドで作成する機能を指定します。When configuring a strategy on the context as the default, you specify a function that creates a new strategy on demand. 次のコードは、 DbConfiguration 基本クラスを拡張する、再試行構成クラスを作成する方法を示しています。The following code shows how you can create a retry configuration class that extends the DbConfiguration base class.

public class BloggingContextConfiguration : DbConfiguration
{
  public BlogConfiguration()
  {
    // Set up the execution strategy for SQL Database (exponential) with 5 retries and 4 sec delay
    this.SetExecutionStrategy(
         "System.Data.SqlClient", () => new SqlAzureExecutionStrategy(5, TimeSpan.FromSeconds(4)));
  }
}

アプリケーションを起動したときに DbConfiguration インスタンスの SetConfiguration メソッドを使用して、すべての操作に対する既定の再試行戦略として、これを指定することができます。You can then specify this as the default retry strategy for all operations using the SetConfiguration method of the DbConfiguration instance when the application starts. 既定では、EF は構成クラスを自動的に検出して使用します。By default, EF will automatically discover and use the configuration class.

DbConfiguration.SetConfiguration(new BloggingContextConfiguration());

コンテキスト クラスに DbConfigurationType 属性で注釈を付けることにより、コンテキストに対して再試行構成クラスを指定できます。You can specify the retry configuration class for a context by annotating the context class with a DbConfigurationType attribute. ただし、構成クラスが 1 つしかない場合、EF はコンテキストに注釈を付けずにそれを使用します。However, if you have only one configuration class, EF will use it without the need to annotate the context.

[DbConfigurationType(typeof(BloggingContextConfiguration))]
public class BloggingContext : DbContext

特定の操作に対して異なる再試行戦略を使用する必要があるか、または特定の操作に対する再試行を無効にする必要がある場合、 CallContextにフラグを設定することで、戦略を中断またはスワップできる構成クラスを作成することができます。If you need to use different retry strategies for specific operations, or disable retries for specific operations, you can create a configuration class that allows you to suspend or swap strategies by setting a flag in the CallContext. 構成クラスでは、このフラグを使用して、戦略を切り替えたり、指定した戦略を無効にして既定の戦略を使用したりできます。The configuration class can use this flag to switch strategies, or disable the strategy you provide and use a default strategy. 詳しくは、実行戦略の中断 (EF6 以降) に関する記事を参照してください。For more information, see Suspend Execution Strategy (EF6 onwards).

個々の操作に特定の再試行戦略を使用する別の手法として、必要な戦略クラスのインスタンスを作成し、パラメーターにより目的の設定を指定することができます。Another technique for using specific retry strategies for individual operations is to create an instance of the required strategy class and supply the desired settings through parameters. 次に、その ExecuteAsync メソッドを呼び出します。You then invoke its ExecuteAsync method.

var executionStrategy = new SqlAzureExecutionStrategy(5, TimeSpan.FromSeconds(4));
var blogs = await executionStrategy.ExecuteAsync(
    async () =>
    {
        using (var db = new BloggingContext("Blogs"))
        {
            // Acquire some values asynchronously and return them
        }
    },
    new CancellationToken()
);

DbConfiguration クラスを使用する最も簡単な方法は、それを DbContext クラスと同じアセンブリ内に配置することです。The simplest way to use a DbConfiguration class is to locate it in the same assembly as the DbContext class. ただし、異なるシナリオ (対話型やバックグラウンドでの再試行戦略が異なるなど) で同じコンテキストが必要な場合には、これは適しません。However, this is not appropriate when the same context is required in different scenarios, such as different interactive and background retry strategies. 異なるコンテキストを別の Appdomain で実行する場合は、構成ファイル内で構成クラスを指定するために組み込みサポートを使用するか、またはコードを使用して構成クラスを明示的に設定することができます。If the different contexts execute in separate AppDomains, you can use the built-in support for specifying configuration classes in the configuration file or set it explicitly using code. 異なる複数のコンテキストを同じ AppDomain 内で実行する必要がある場合には、カスタム ソリューションが必要です。If the different contexts must execute in the same AppDomain, a custom solution will be required.

詳細については、「コード ベースの構成 (EF6 以降)」を参照してください。For more information, see Code-Based Configuration (EF6 onwards).

次の表は、EF6 を使用している場合の、組み込み再試行ポリシーの既定の設定を示しています。The following table shows the default settings for the built-in retry policy when using EF6.

設定Setting 既定値Default value 意味Meaning
ポリシーPolicy 指数Exponential 指数バックオフ。Exponential back-off.
MaxRetryCountMaxRetryCount 55 最大再試行回数。The maximum number of retries.
MaxDelayMaxDelay 30 秒30 seconds 再試行間の最大遅延。The maximum delay between retries. この値は一連の遅延の計算方法には影響しません。This value does not affect how the series of delays are computed. 上限値のみが定義されます。It only defines an upper bound.
DefaultCoefficientDefaultCoefficient 1 秒1 second 指数バックオフ計算の係数。The coefficient for the exponential back-off computation. この値は変更できません。This value cannot be changed.
DefaultRandomFactorDefaultRandomFactor 1.11.1 各エントリのランダム遅延を追加するために使用する乗数。The multiplier used to add a random delay for each entry. この値は変更できません。This value cannot be changed.
DefaultExponentialBaseDefaultExponentialBase 22 次の遅延を計算するために使用する乗数。The multiplier used to calculate the next delay. この値は変更できません。This value cannot be changed.

再試行使用のガイダンスRetry usage guidance

EF6 を使用して SQL Database にアクセスする場合は、次のガイドラインを検討します。Consider the following guidelines when accessing SQL Database using EF6:

  • 適切なサービス オプション (Shared または Premium) を選択します。Choose the appropriate service option (shared or premium). 共有インスタンスは、共有サーバーの他のテナントによる使用状況により、通常よりも長い接続遅延や調整の影響を受ける可能性があります。A shared instance may suffer longer than usual connection delays and throttling due to the usage by other tenants of the shared server. 予測可能なパフォーマンスと信頼性の高い低待機時間での操作が必要な場合は、Premium オプションを選択することを検討してください。If predictable performance and reliable low latency operations are required, consider choosing the premium option.

  • 固定間隔戦略を Azure SQL Database で使用することは推奨されていません。A fixed interval strategy is not recommended for use with Azure SQL Database. 代わりに、指数バックオフ戦略を使用します。サービスがオーバーロードする可能性があり、遅延が長くなれば回復するための時間をより多くとることができるからです。Instead, use an exponential back-off strategy because the service may be overloaded, and longer delays allow more time for it to recover.

  • 接続を定義するときは、接続タイムアウトとコマンド タイムアウトに適切な値を選択します。Choose a suitable value for the connection and command timeouts when defining connections. タイムアウトは、ビジネス ロジック設計と十分なテストの両方に基づいた値にします。Base the timeout on both your business logic design and through testing. この値は、時間の経過によるデータの量やビジネス プロセスの変化に応じて、変更することが必要になる場合があります。You may need to modify this value over time as the volumes of data or the business processes change. タイムアウトが短すぎると、データベースがビジー状態の場合に、接続が途中でエラーになる可能性があります。Too short a timeout may result in premature failures of connections when the database is busy. タイムアウトが長すぎると、接続エラーを検出するまで長く待ちすぎて、再試行ロジックが正常に機能しなくなる可能性があります。Too long a timeout may prevent the retry logic working correctly by waiting too long before detecting a failed connection. コンテキストの保存時に実行されるコマンドの数は簡単には特定できないとしても、タイムアウトの値は、エンドツーエンド待機時間の構成要素です。The value of the timeout is a component of the end-to-end latency, although you cannot easily determine how many commands will execute when saving the context. 既定のタイムアウトは、DbContext インスタンスの CommandTimeout プロパティを設定することで変更できます。You can change the default timeout by setting the CommandTimeout property of the DbContext instance.

  • Entity Framework は、構成ファイルで定義されている再試行構成をサポートします。Entity Framework supports retry configurations defined in configuration files. ただし、Azure 上で最大の柔軟性を実現するために、アプリケーション内でプログラムを使用して構成を作成することを検討してください。However, for maximum flexibility on Azure you should consider creating the configuration programmatically within the application. 再試行ポリシーの特定のパラメーター (再試行数や再試行間隔など) は、サービス構成ファイルに格納して、実行時に適切なポリシーを作成するために使用することができます。The specific parameters for the retry policies, such as the number of retries and the retry intervals, can be stored in the service configuration file and used at runtime to create the appropriate policies. これにより、アプリケーションを再起動する必要なく設定を変更できます。This allows the settings to be changed without requiring the application to be restarted.

再試行操作を次の設定から始めることを検討してください。Consider starting with the following settings for retrying operations. 再試行間の遅延を指定することはできません (固定されており、指数のシーケンスとして生成されます)。You cannot specify the delay between retry attempts (it is fixed and generated as an exponential sequence). カスタム再試行戦略を作成しない限り、ここに示すとおり、指定できるのは最大値のみです。You can specify only the maximum values, as shown here; unless you create a custom retry strategy. これらの設定は汎用であり、操作を監視して、独自のシナリオに合うように値を微調整する必要があります。These settings are general purpose, and you should monitor the operations and fine-tune the values to suit your own scenario.

コンテキストContext サンプルのターゲット E2E
最大待機時間
Sample target E2E
max latency
再試行ポリシーRetry policy 設定Settings Values 動作のしくみHow it works
対話型、UI、Interactive, UI,
またはフォアグラウンドor foreground
2 秒2 seconds 指数Exponential MaxRetryCountMaxRetryCount
MaxDelayMaxDelay
33
750 ミリ秒750 ms
試行 1 - 0 秒の遅延Attempt 1 - delay 0 sec
試行 2 - 750 ミリ秒の遅延Attempt 2 - delay 750 ms
試行 3 - 750 ミリ秒の遅延Attempt 3 – delay 750 ms
バックグラウンドBackground
またはバッチor batch
30 秒30 seconds 指数Exponential MaxRetryCountMaxRetryCount
MaxDelayMaxDelay
55
12 秒12 seconds
試行 1 - 0 秒の遅延Attempt 1 - delay 0 sec
試行 2 - 最大 1 秒の遅延Attempt 2 - delay ~1 sec
試行 3 - 最大 3 秒の遅延Attempt 3 - delay ~3 sec
試行 4 - 最大 7 秒の遅延Attempt 4 - delay ~7 sec
試行 5 - 12 秒の遅延Attempt 5 - delay 12 sec

注意

エンドツーエンド待機時間のターゲットには、サービスへの接続用の既定のタイムアウトが想定されます。The end-to-end latency targets assume the default timeout for connections to the service. 接続タイムアウトにより長い時間を指定する場合、エンドツーエンド待機時間は、すべての再試行についてこの追加時間分だけ延長されます。If you specify longer connection timeouts, the end-to-end latency will be extended by this additional time for every retry attempt.

Examples

次のコード例は、Entity Framework を使用する単純なデータ アクセス ソリューションを定義します。The following code example defines a simple data access solution that uses Entity Framework. これは、DbConfiguration を拡張する BlogConfiguration というクラスのインスタンスを定義することで、特定の再試行戦略を設定します。It sets a specific retry strategy by defining an instance of a class named BlogConfiguration that extends DbConfiguration.

using System;
using System.Collections.Generic;
using System.Data.Entity;
using System.Data.Entity.SqlServer;
using System.Threading.Tasks;

namespace RetryCodeSamples
{
    public class BlogConfiguration : DbConfiguration
    {
        public BlogConfiguration()
        {
            // Set up the execution strategy for SQL Database (exponential) with 5 retries and 12 sec delay.
            // These values could be loaded from configuration rather than being hard-coded.
            this.SetExecutionStrategy(
                    "System.Data.SqlClient", () => new SqlAzureExecutionStrategy(5, TimeSpan.FromSeconds(12)));
        }
    }

    // Specify the configuration type if more than one has been defined.
    // [DbConfigurationType(typeof(BlogConfiguration))]
    public class BloggingContext : DbContext
    {
        // Definition of content goes here.
    }

    class EF6CodeSamples
    {
        public async static Task Samples()
        {
            // Execution strategy configured by DbConfiguration subclass, discovered automatically or
            // or explicitly indicated through configuration or with an attribute. Default is no retries.
            using (var db = new BloggingContext("Blogs"))
            {
                // Add, edit, delete blog items here, then:
                await db.SaveChangesAsync();
            }
        }
    }
}

Entity Framework の再試行メカニズムを使用する他の例については、「Connection Resiliency / Retry Logic (接続の回復/再試行ロジック)」を参照してください。More examples of using the Entity Framework retry mechanism can be found in Connection Resiliency / Retry Logic.

詳細情報More information

Entity Framework Core を使用した SQL Database アクセスSQL Database using Entity Framework Core

Entity Framework Core は、.NET Core 開発者がドメイン固有オブジェクトを使用してリレーショナル データを操作できるようにする、オブジェクト リレーショナル マッパーです。Entity Framework Core is an object-relational mapper that enables .NET Core developers to work with data using domain-specific objects. これにより、開発者が通常は記述する必要のあるデータアクセス コードの大部分が不要になります。It eliminates the need for most of the data-access code that developers usually need to write. このバージョンの Entity Framework は一から作成されているため、EF6.x の機能の一部は自動的に継承されません。This version of Entity Framework was written from the ground up, and doesn't automatically inherit all the features from EF6.x.

再試行メカニズムRetry mechanism

再試行サポートは、SQL Database データベースに接続の弾力性というメカニズム経由で Entity Framework Core を使用してアクセスするときに提供されます。Retry support is provided when accessing SQL Database using Entity Framework Core through a mechanism called connection resiliency. 接続の弾力性は、EF Core 1.1.0 で導入されました。Connection resiliency was introduced in EF Core 1.1.0.

プライマリの抽象型は、IExecutionStrategy インターフェイスです。The primary abstraction is the IExecutionStrategy interface. SQL Azure を含む SQL Server の実行戦略では、再試行できる例外タイプが認識されており、最大再試行回数、再試行間の遅延などについて実用的な既定値が設定されています。The execution strategy for SQL Server, including SQL Azure, is aware of the exception types that can be retried and has sensible defaults for maximum retries, delay between retries, and so on.

Examples

次のコードは、データベースとのセッションを表す DbContext オブジェクトを構成するときの自動再試行を実行します。The following code enables automatic retries when configuring the DbContext object, which represents a session with the database.

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder
        .UseSqlServer(
            @"Server=(localdb)\mssqllocaldb;Database=EFMiscellaneous.ConnectionResiliency;Trusted_Connection=True;",
            options => options.EnableRetryOnFailure());
}

次のコードは、実行戦略に従った、自動再試行を使用したトランザクションの実行方法を示しています。The following code shows how to execute a transaction with automatic retries, by using an execution strategy. トランザクションは、デリゲート内で定義されています。The transaction is defined in a delegate. 一時的な障害が発生した場合、実行戦略は、デリゲートをもう一度呼び出します。If a transient failure occurs, the execution strategy will invoke the delegate again.

using (var db = new BloggingContext())
{
    var strategy = db.Database.CreateExecutionStrategy();

    strategy.Execute(() =>
    {
        using (var transaction = db.Database.BeginTransaction())
        {
            db.Blogs.Add(new Blog { Url = "https://blogs.msdn.com/dotnet" });
            db.SaveChanges();

            db.Blogs.Add(new Blog { Url = "https://blogs.msdn.com/visualstudio" });
            db.SaveChanges();

            transaction.Commit();
        }
    });
}

Azure StorageAzure Storage

Azure Storage サービスには、テーブル、Blob Storage、ファイル、およびストレージ キューが含まれています。Azure Storage services include table and blob storage, files, and storage queues.

再試行メカニズムRetry mechanism

再試行は、個々の REST 操作レベルで実行され、クライアント API 実装の不可欠な部分です。Retries occur at the individual REST operation level and are an integral part of the client API implementation. クライアント ストレージ SDK は、 IExtendedRetryPolicy インターフェイスを実装するクラスを使用します。The client storage SDK uses classes that implement the IExtendedRetryPolicy Interface.

このインターフェイスにはさまざまな実装があります。There are different implementations of the interface. ストレージ クライアントは、ポリシーを、テーブル、BLOB、およびキューにアクセスするために設計されたものの中から選択できます。Storage clients can choose from policies designed for accessing tables, blobs, and queues. 各実装は、基本的に、再試行間隔や他の詳細を定義する、それぞれに異なる再試行戦略を使用します。Each implementation uses a different retry strategy that essentially defines the retry interval and other details.

組み込みクラスは、Linear (一定遅延) と、ランダム化された再試行間隔が指定される Exponential をサポートします。The built-in classes provide support for linear (constant delay) and exponential with randomization retry intervals. 別のプロセスがより高いレベルで再試行を処理している場合に使用する、再試行なしポリシーもあります。There is also a no retry policy for use when another process is handling retries at a higher level. ただし、組み込みクラスによって提供されていない特定の要件がある場合は、独自の再試行クラスを実装できます。However, you can implement your own retry classes if you have specific requirements not provided by the built-in classes.

代替再試行では、読み取りアクセス geo 冗長ストレージ (RA-GRS) を使用しており、要求の結果が再試行可能エラーになる場合は、プライマリとセカンダリのストレージ サービス場所での切り替えが行われます。Alternate retries switch between primary and secondary storage service location if you are using read access geo-redundant storage (RA-GRS) and the result of the request is a retryable error. 詳細については、「Azure Storage 冗長オプション」を参照してください。See Azure Storage Redundancy Options for more information.

ポリシーの構成Policy configuration

再試行ポリシーは、プログラムにより構成されます。Retry policies are configured programmatically. 一般的なプロシージャでは、TableRequestOptionsBlobRequestOptionsFileRequestOptions、または QueueRequestOptions の各インスタンスが作成されて設定されます。A typical procedure is to create and populate a TableRequestOptions, BlobRequestOptions, FileRequestOptions, or QueueRequestOptions instance.

TableRequestOptions interactiveRequestOption = new TableRequestOptions()
{
  RetryPolicy = new LinearRetry(TimeSpan.FromMilliseconds(500), 3),
  // For Read-access geo-redundant storage, use PrimaryThenSecondary.
  // Otherwise set this to PrimaryOnly.
  LocationMode = LocationMode.PrimaryThenSecondary,
  // Maximum execution time based on the business use case.
  MaximumExecutionTime = TimeSpan.FromSeconds(2)
};

要求オプション インスタンスは、クライアントに対して設定することができ、そのクライアントからのすべての操作は、指定された要求オプションを使用します。The request options instance can then be set on the client, and all operations with the client will use the specified request options.

client.DefaultRequestOptions = interactiveRequestOption;
var stats = await client.GetServiceStatsAsync();

クライアント要求オプションは、要求オプション クラスの設定済みインスタンスを操作メソッドのパラメーターとして渡すことによって、オーバーライドできます。You can override the client request options by passing a populated instance of the request options class as a parameter to operation methods.

var stats = await client.GetServiceStatsAsync(interactiveRequestOption, operationContext: null);

OperationContext インスタンスは、再試行が行われたときと操作が完了したときに実行するコードの指定に使用できます。You use an OperationContext instance to specify the code to execute when a retry occurs and when an operation has completed. このコードは、ログとテレメトリで使用する、操作に関する情報を収集できます。This code can collect information about the operation for use in logs and telemetry.

// Set up notifications for an operation
var context = new OperationContext();
context.ClientRequestID = "some request id";
context.Retrying += (sender, args) =>
{
    // Collect retry information
};
context.RequestCompleted += (sender, args) =>
{
    // Collect operation completion information
};
var stats = await client.GetServiceStatsAsync(null, context);

さらに、エラーに対して再試行が適切であるかどうかを示すために、拡張再試行ポリシーは、再試行回数、前回の要求の結果、次回の再試行が行われる場所 (プライマリまたはセカンダリ) を示す、 RetryContext オブジェクトを返します (詳細については、次の表を参照してください)。In addition to indicating whether a failure is suitable for retry, the extended retry policies return a RetryContext object that indicates the number of retries, the results of the last request, whether the next retry will happen in the primary or secondary location (see table below for details). RetryContext オブジェクトのプロパティは、再試行を行うかどうか、およびいつ行うかを決定するために使用できます。The properties of the RetryContext object can be used to decide if and when to attempt a retry. 詳細については、IExtendedRetryPolicy.Evaluate メソッドを参照してください。For more information, see IExtendedRetryPolicy.Evaluate Method.

次の表は、組み込み再試行ポリシーの既定の設定を示しています。The following tables show the default settings for the built-in retry policies.

要求のオプション:Request options:

設定Setting 既定値Default value 意味Meaning
MaximumExecutionTimeMaximumExecutionTime なしNone 要求の最大実行時間 (考えられるすべての再試行が含まれます)。Maximum execution time for the request, including all potential retry attempts. 指定しない場合、要求が許可されるのにかかる時間に制限がなくなります。If it is not specified, then the amount of time that a request is permitted to take is unlimited. つまり、要求が応答しなくなることがあります。In other words, the request might stop responding.
ServerTimeoutServerTimeout なしNone 要求のサーバー タイムアウト間隔 (値は秒単位に丸められます)。Server timeout interval for the request (value is rounded to seconds). 指定しない場合、サーバーに対するすべての要求に既定値が使用されます。If not specified, it will use the default value for all requests to the server. 通常、この設定を省略してサーバーの既定値が使用されるようにすることが最善のオプションになります。Usually, the best option is to omit this setting so that the server default is used.
LocationModeLocationMode なしNone ストレージ アカウントが読み取りアクセス geo 冗長ストレージ (RA-GRS) のレプリケーション オプションを指定して作成されている場合、場所モードを使用して、要求を受け取る場所を示すことができます。If the storage account is created with the Read access geo-redundant storage (RA-GRS) replication option, you can use the location mode to indicate which location should receive the request. たとえば、PrimaryThenSecondary を指定した場合、要求は必ず最初にプライマリの場所に送信されます。For example, if PrimaryThenSecondary is specified, requests are always sent to the primary location first. 失敗した場合、要求はセカンダリの場所に送信されます。If a request fails, it is sent to the secondary location.
RetryPolicyRetryPolicy ExponentialPolicyExponentialPolicy 各オプションの詳細については、以下をご覧ください。See below for details of each option.

Exponential ポリシー:Exponential policy:

設定Setting 既定値Default value 意味Meaning
maxAttemptmaxAttempt 33 再試行回数。Number of retry attempts.
deltaBackoffdeltaBackoff 4 秒4 seconds 再試行のバックオフ間隔。Back-off interval between retries. この期間のランダムな倍数が、後続の再試行に使用されます。Multiples of this timespan, including a random element, will be used for subsequent retry attempts.
MinBackoffMinBackoff 3 秒3 seconds deltaBackoff から計算されたすべての再試行間隔に追加されます。Added to all retry intervals computed from deltaBackoff. この値は変更できません。This value cannot be changed.
MaxBackoffMaxBackoff 120 秒120 seconds MaxBackoff は、計算された再試行間隔が MaxBackoff より大きい場合に使用されます。MaxBackoff is used if the computed retry interval is greater than MaxBackoff. この値は変更できません。This value cannot be changed.

Linear ポリシー:Linear policy:

設定Setting 既定値Default value 意味Meaning
maxAttemptmaxAttempt 33 再試行回数。Number of retry attempts.
deltaBackoffdeltaBackoff 30 秒30 seconds 再試行のバックオフ間隔。Back-off interval between retries.

再試行使用のガイダンスRetry usage guidance

ストレージ クライアント API を使用して Microsoft Azure Storage サービスにアクセスする場合は、次のガイドラインを検討します。Consider the following guidelines when accessing Azure storage services using the storage client API:

  • Microsoft.Azure.Storage.RetryPolicies 名前空間からの組み込み再試行ポリシーを使用します (これらのポリシーが要件に適している場合)。Use the built-in retry policies from the Microsoft.Azure.Storage.RetryPolicies namespace where they are appropriate for your requirements. ほとんどの場合、これらのポリシーで十分対応できます。In most cases, these policies will be sufficient.

  • バッチ操作、バックグラウンド タスク、または非対話型のシナリオでは、ExponentialRetry ポリシーを使用します。Use the ExponentialRetry policy in batch operations, background tasks, or non-interactive scenarios. これらのシナリオでは、一般に、サービスを復旧するためにより多くの時間を確保できます—結果として、操作は最終的に成功する可能性が高くなります。In these scenarios, you can typically allow more time for the service to recover—with a consequently increased chance of the operation eventually succeeding.

  • 合計実行時間を制限するには、RequestOptions パラメーターの MaximumExecutionTime プロパティを指定することを検討してください。ただし、タイムアウト値を選択する場合は、操作の種類とサイズを考慮に入れてください。Consider specifying the MaximumExecutionTime property of the RequestOptions parameter to limit the total execution time, but take into account the type and size of the operation when choosing a timeout value.

  • カスタム再試行を実装する必要がある場合は、ストレージ クライアント クラスを囲むラッパーは作成しないでください。If you need to implement a custom retry, avoid creating wrappers around the storage client classes. 代わりに IExtendedRetryPolicy インターフェイスから、既存のポリシーを拡張する機能を使用してください。Instead, use the capabilities to extend the existing policies through the IExtendedRetryPolicy interface.

  • 読み取りアクセス geo 冗長ストレージ (RA-GRS) を使用している場合、 LocationMode を使用して、プライマリへのアクセスが失敗した場合に、再試行がストアのセカンダリ読み取り専用コピーにアクセスするように指定できます。If you are using read access geo-redundant storage (RA-GRS) you can use the LocationMode to specify that retry attempts will access the secondary read-only copy of the store should the primary access fail. ただし、このオプションを使用するときは、プライマリ ストアからのレプリケーションがまだ完了していない場合に、古くなった可能性があるデータを用いてアプリケーションが正常に動作できることを確認する必要があります。However, when using this option you must ensure that your application can work successfully with data that may be stale if the replication from the primary store has not yet completed.

再試行操作を次の設定から始めることを検討してください。Consider starting with the following settings for retrying operations. これらの設定は汎用であり、操作を監視して、独自のシナリオに合うように値を微調整する必要があります。These settings are general purpose, and you should monitor the operations and fine-tune the values to suit your own scenario.

コンテキストContext サンプルのターゲット E2E
最大待機時間
Sample target E2E
max latency
再試行ポリシーRetry policy 設定Settings Values 動作のしくみHow it works
対話型、UI、Interactive, UI,
またはフォアグラウンドor foreground
2 秒2 seconds LinearLinear maxAttemptmaxAttempt
deltaBackoffdeltaBackoff
33
500 ミリ秒500 ms
試行 1 - 500 ミリ秒の遅延Attempt 1 - delay 500 ms
試行 2 - 500 ミリ秒の遅延Attempt 2 - delay 500 ms
試行 3 - 500 ミリ秒の遅延Attempt 3 - delay 500 ms
バックグラウンドBackground
またはバッチor batch
30 秒30 seconds 指数Exponential maxAttemptmaxAttempt
deltaBackoffdeltaBackoff
55
4 秒4 seconds
試行 1 - 最大 3 秒の遅延Attempt 1 - delay ~3 sec
試行 2 - 最大 7 秒の遅延Attempt 2 - delay ~7 sec
試行 3 - 最大 15 秒の遅延Attempt 3 - delay ~15 sec

テレメトリTelemetry

再試行回数は TraceSourceに記録されます。Retry attempts are logged to a TraceSource. イベントをキャプチャし、それらを適切な宛先ログに書き込むには、TraceListener を構成する必要があります。You must configure a TraceListener to capture the events and write them to a suitable destination log. データをログ ファイルに書き込むには TextWriterTraceListener または XmlWriterTraceListener を、Windows イベント ログに書き込むには EventLogTraceListener を、トレース データを ETW サブシステムに書き込むには EventProviderTraceListener をそれぞれ使用できます。You can use the TextWriterTraceListener or XmlWriterTraceListener to write the data to a log file, the EventLogTraceListener to write to the Windows Event Log, or the EventProviderTraceListener to write trace data to the ETW subsystem. バッファーの自動フラッシュと、ログに記録するイベントの詳細度 (たとえば、エラー、警告、情報、および冗長など) を構成することもできます。You can also configure autoflushing of the buffer, and the verbosity of events that will be logged (for example, Error, Warning, Informational, and Verbose). 詳細については、「 .NET ストレージ クライアント ライブラリによるクライアント側のログ」を参照してください。For more information, see Client-side Logging with the .NET Storage Client Library.

操作は OperationContext インスタンスを受け取る可能性があります。これはカスタム テレメトリ ロジックをアタッチするために使用できる Retrying イベントを公開します。Operations can receive an OperationContext instance, which exposes a Retrying event that can be used to attach custom telemetry logic. 詳細については、「OperationContext.Retrying Event (OperationContext.Retrying イベント)」を参照してください。For more information, see OperationContext.Retrying Event.

Examples

次のコード例は、異なる再試行設定で 2 つの TableRequestOptions インスタンスを作成する方法を示しています。1 つは対話型の要求向け、1 つはバックグラウンドの要求向けです。The following code example shows how to create two TableRequestOptions instances with different retry settings; one for interactive requests and one for background requests. 次にこの例では、これら 2 つの再試行ポリシーをクライアントに対して設定して、それらのポリシーがすべての要求に適用されるようにします。さらに、対話型戦略を特定の要求に対して設定して、クライアントに適用された既定の設定をオーバーライドできるようにします。The example then sets these two retry policies on the client so that they apply for all requests, and also sets the interactive strategy on a specific request so that it overrides the default settings applied to the client.

using System;
using System.Threading.Tasks;
using Microsoft.WindowsAzure.Storage;
using Microsoft.WindowsAzure.Storage.RetryPolicies;
using Microsoft.WindowsAzure.Storage.Table;

namespace RetryCodeSamples
{
    class AzureStorageCodeSamples
    {
        private const string connectionString = "UseDevelopmentStorage=true";

        public async static Task Samples()
        {
            var storageAccount = CloudStorageAccount.Parse(connectionString);

            TableRequestOptions interactiveRequestOption = new TableRequestOptions()
            {
                RetryPolicy = new LinearRetry(TimeSpan.FromMilliseconds(500), 3),
                // For Read-access geo-redundant storage, use PrimaryThenSecondary.
                // Otherwise set this to PrimaryOnly.
                LocationMode = LocationMode.PrimaryThenSecondary,
                // Maximum execution time based on the business use case.
                MaximumExecutionTime = TimeSpan.FromSeconds(2)
            };

            TableRequestOptions backgroundRequestOption = new TableRequestOptions()
            {
                // Client has a default exponential retry policy with 4 sec delay and 3 retry attempts
                // Retry delays will be approximately 3 sec, 7 sec, and 15 sec
                MaximumExecutionTime = TimeSpan.FromSeconds(30),
                // PrimaryThenSecondary in case of Read-access geo-redundant storage, else set this to PrimaryOnly
                LocationMode = LocationMode.PrimaryThenSecondary
            };

            var client = storageAccount.CreateCloudTableClient();
            // Client has a default exponential retry policy with 4 sec delay and 3 retry attempts
            // Retry delays will be approximately 3 sec, 7 sec, and 15 sec
            // ServerTimeout and MaximumExecutionTime are not set

            {
                // Set properties for the client (used on all requests unless overridden)
                // Different exponential policy parameters for background scenarios
                client.DefaultRequestOptions = backgroundRequestOption;
                // Linear policy for interactive scenarios
                client.DefaultRequestOptions = interactiveRequestOption;
            }

            {
                // set properties for a specific request
                var stats = await client.GetServiceStatsAsync(interactiveRequestOption, operationContext: null);
            }

            {
                // Set up notifications for an operation
                var context = new OperationContext();
                context.ClientRequestID = "some request id";
                context.Retrying += (sender, args) =>
                {
                    // Collect retry information
                };
                context.RequestCompleted += (sender, args) =>
                {
                    // Collect operation completion information
                };
                var stats = await client.GetServiceStatsAsync(null, context);
            }
        }
    }
}

詳細情報More information

一般的な REST および再試行のガイドラインGeneral REST and retry guidelines

Azure またはサード パーティ提供のサービスにアクセスする場合は、次の事柄を考慮してください。Consider the following when accessing Azure or third-party services:

  • 再試行の管理に体系的な方法を使用し (再利用可能コードとするなど)、すべてのクライアントとすべてのソリューションの間で一貫性のある方式を適用できるようにします。Use a systematic approach to managing retries, perhaps as reusable code, so that you can apply a consistent methodology across all clients and all solutions.

  • 対象となるサービスまたはクライアントに再試行メカニズムが組み込まれていない場合は、Polly などの再試行フレームワークを使用して再試行を管理することを検討します。Consider using a retry framework such as Polly to manage retries if the target service or client has no built-in retry mechanism. これは、一貫性のある再試行動作を実装するのに役立ち、ターゲットのサービスに適切な既定の再試行戦略を提供することができます。This will help you implement a consistent retry behavior, and it may provide a suitable default retry strategy for the target service. ただし、非標準動作を持つサービスと一時的エラーを示す例外に依存しないサービス用に、カスタム再試行コードを作成することが必要になる場合があります。また、再試行動作を管理するために Retry-Response 応答を使用する場合も、カスタム再試行コードの作成が必要になることがあります。However, you may need to create custom retry code for services that have nonstandard behavior, that do not rely on exceptions to indicate transient failures, or if you want to use a Retry-Response reply to manage retry behavior.

  • 一時的なエラー検出ロジックは、REST 呼び出しの実行に使用する、実際のクライアント API によって異なります。The transient detection logic will depend on the actual client API you use to invoke the REST calls. 比較的新しい HttpClient クラスなどの一部のクライアントは、不成功 HTTP 状態コードで完了した要求には例外をスローしません。Some clients, such as the newer HttpClient class, will not throw exceptions for completed requests with a non-success HTTP status code.

  • サービスから返される HTTP 状態コードは、エラーが一時的なものであるかどうかを知るのに役立ちます。The HTTP status code returned from the service can help to indicate whether the failure is transient. 状態コードにアクセスするか、または同等の例外の種類を判別するには、クライアントまたは再試行フレームワークによって生成される例外を調べることが必要になる場合があります。You may need to examine the exceptions generated by a client or the retry framework to access the status code or to determine the equivalent exception type. 一般に、次の HTTP コードは、再試行が適切であることを示します。The following HTTP codes typically indicate that a retry is appropriate:

    • 408 要求タイムアウト408 Request Timeout
    • 429 Too Many Requests429 Too Many Requests
    • 500 内部サーバー エラー500 Internal Server Error
    • 502 無効なゲートウェイ502 Bad Gateway
    • 503 サービス利用不可503 Service Unavailable
    • 504 ゲートウェイ タイムアウト504 Gateway Timeout
  • 再試行ロジックを例外に基づくものにしている場合、次のものは一般に、接続が確立できなかった一時的なエラーを示しています。If you base your retry logic on exceptions, the following typically indicate a transient failure where no connection could be established:

    • WebExceptionStatus.ConnectionClosedWebExceptionStatus.ConnectionClosed
    • WebExceptionStatus.ConnectFailureWebExceptionStatus.ConnectFailure
    • WebExceptionStatus.TimeoutWebExceptionStatus.Timeout
    • WebExceptionStatus.RequestCanceledWebExceptionStatus.RequestCanceled
  • サービス使用不可状態は、サービスが Retry-After 応答ヘッダーまたは別のカスタム ヘッダーで、再試行前の適切な遅延を示している場合があります。In the case of a service unavailable status, the service might indicate the appropriate delay before retrying in the Retry-After response header or a different custom header. サービスは、カスタム ヘッダーとして、または応答の内容に埋め込んで、追加情報を送信することもあります。Services might also send additional information as custom headers, or embedded in the content of the response.

  • 408 (要求タイムアウト) および 429 (要求が多すぎます) を除き、クライアント エラー (4xx の範囲内のエラー) を表す状態コードに対しては再試行しないでください。Do not retry for status codes representing client errors (errors in the 4xx range) except for a 408 Request Timeout and 429 Too Many Requests.

  • 再試行戦略および再試行メカニズムは、多様なネットワーク状態やさまざまなシステム負荷などの幅広い条件下で十分にテストします。Thoroughly test your retry strategies and mechanisms under a range of conditions, such as different network states and varying system loadings.

再試行戦略Retry strategies

次に示すのは、標準的な種類の再試行戦略間隔です。The following are the typical types of retry strategy intervals:

  • ExponentialExponential. 指定回数の再試行を実行し、ランダムな指数バックオフ アプローチを使用して再試行間の間隔を決定する再試行ポリシーです。A retry policy that performs a specified number of retries, using a randomized exponential back off approach to determine the interval between retries. 次に例を示します。For example:

    var random = new Random();
    
    var delta = (int)((Math.Pow(2.0, currentRetryCount) - 1.0) *
                random.Next((int)(this.deltaBackoff.TotalMilliseconds * 0.8),
                (int)(this.deltaBackoff.TotalMilliseconds * 1.2)));
    var interval = (int)Math.Min(checked(this.minBackoff.TotalMilliseconds + delta),
                    this.maxBackoff.TotalMilliseconds);
    retryInterval = TimeSpan.FromMilliseconds(interval);
    
  • IncrementalIncremental. 指定回数の再試行を実行し、再試行ごとに時間間隔を長くする再試行戦略です。A retry strategy with a specified number of retry attempts and an incremental time interval between retries. 次に例を示します。For example:

    retryInterval = TimeSpan.FromMilliseconds(this.initialInterval.TotalMilliseconds +
                    (this.increment.TotalMilliseconds * currentRetryCount));
    
  • LinearRetryLinearRetry. 指定回数の再試行を実行し、再試行間には指定の固定時間間隔を使用する再試行ポリシーです。A retry policy that performs a specified number of retries, using a specified fixed time interval between retries. 次に例を示します。For example:

    retryInterval = this.deltaBackoff;
    

Polly での一時的な障害処理Transient fault handling with Polly

Polly は、再試行およびサーキット ブレーカー戦略をプログラムで処理するライブラリです。Polly is a library to programmatically handle retries and circuit breaker strategies. Polly プロジェクトは、.NET Foundation のメンバーです。The Polly project is a member of the .NET Foundation. クライアントがネイティブで再試行をサポートしないサービスでは、Polly は有効な代替手段で、正しく実装することが難しい可能性もある、カスタム再試行コードを書く必要がなくなります。For services where the client does not natively support retries, Polly is a valid alternative and avoids the need to write custom retry code, which can be hard to implement correctly. Polly でも、再試行をログに記録できるよう、エラーを追跡する方法が提供されています。Polly also provides a way to trace errors when they occur, so that you can log retries.

詳細情報More information