SharePoint Online で調整またはブロックを回避するAvoid getting throttled or blocked in SharePoint Online

ここでは、SharePoint Online の調整を説明し、調整とブロックを回避する方法を検討します。Find out about throttling in SharePoint Online, and learn how to avoid being throttled or blocked. 簡単に使用できる CSOM サンプルと REST コードも紹介します。Includes sample CSOM and REST code you can use to make your task easier.

SharePoint Online でファイルを移行するときなどに CSOM プロセスが実行されるものの調整されていることがよくありますか。さらに悪いことに、完全にブロックされることさえあります。このような状況の詳細と、これを回避する方法を説明します。Does this sound familiar? You're running a CSOM process - for example, to migrate files in SharePoint Online - but you keep getting throttled. Or even worse, you get completely blocked. What's going on and what can you do to make it stop?

調整とはWhat is throttling?

SharePoint Online は、SharePoint Online サービスの最適なパフォーマンスと信頼性を維持する目的で調整を使用します。調整では、リソースの過剰な使用を防ぐため、ユーザー アクションまたは (スクリプトまたはコードによる) 同時呼び出しの数が制限されます。SharePoint Online uses throttling to maintain optimal performance and reliability of the SharePoint Online service. Throttling limits the number of user actions or concurrent calls (by script or code) to prevent overuse of resources.

ただし、ユーザーが SharePoint Online で調整されるケースは非常に稀です。サービスは堅牢であり、非常に大量のボリュームにも対処できるように設計されています。調整が発生する場合、99% の割合でその原因はカスタム コードにあります。この原因以外に調整が発生することがないというわけではありませんが、そのような状況は一般的ではありません。たとえば 10 台のマシンをスピンアップし、10 台すべてのマシンでクライアント同期が実行され、各マシンで 1TB のコンテンツが同期されるとします。このような状況では調整が発生する可能性があります。That said, it is extremely rare for a user to get throttled in SharePoint Online. The service is robust, and it is designed to handle very high volume. If you do get throttled, 99% of the time it is because of custom code. That doesn't mean that there aren't other ways to get throttled, just that they are less common. For example you spin up 10 machines and have a sync client going on all 10. On each sync 1TB of content. This would likely get you throttled.

調整が生じる方法

SharePoint Online で調整が発生する状況What happens when you get throttled in SharePoint Online?

あるユーザーが使用制限を超えると、そのユーザー アカウントからさらに送られる要求は SharePoint Online によって短時間、調整されます。調整が有効な間、ユーザー操作はすべて調整されます。When a user exceeds usage limits, SharePoint Online throttles any further requests from that user account for a short period. All user actions are throttled while the throttle is in effect.

  • ユーザーがブラウザーで直接実行する要求の場合、SharePoint Online はユーザーを調整情報のページにリダイレクトし、要求は失敗します。For requests that a user performs directly in the browser, SharePoint Online redirects you to the throttling information page, and the requests fail.

  • その他すべての要求の場合 (CSOM または REST 呼び出しを含む)、SharePoint Online は HTTP ステータス コード 429 (「要求が多すぎます」) を返し、要求は失敗します。For all other requests, including CSOM or REST calls, SharePoint Online returns HTTP status code 429 ("Too many requests"), and the requests fail.

問題のあるプロセスが使用制限を超過し続けている場合、SharePoint Online はプロセスを完全にブロックすることがあります。その場合、HTTP ステータス コード 503 (「サービスを使用できません」) が表示されることがあり、Office 365 メッセージ センターからブロックの通知があります。このエラー メッセージを次に示します。If the offending process continues to exceed usage limits, SharePoint Online might completely block the process; in this case, you may see HTTP status code 503 ("Service unavailable"), and we'll notify you of the block in the Office 365 Message Center. The error message is shown below:

[503 サーバーを利用できません] というメッセージ

503 「サービスを使用できません」メッセージ。503 Server unavailable message.

SharePoint Online での一般的な調整シナリオCommon throttling scenarios in SharePoint Online

SharePoint Online でユーザー単位の調整が生じる最も一般的な原因は、クライアント側オブジェクト モデル (CSOM) コードまたは Representational State Transfer (REST) コードで実行される操作の頻度と数が多すぎることです。The most common causes of per-user throttling in SharePoint Online are client-side object model (CSOM) or Representational State Transfer (REST) code that performs too many actions too frequently.

  • 散発的なトラフィックSporadic traffic

    一時点でのトラフィック量は多くないものの、実行期間中にかなりの量のトラフィックが発生すると、断続的に調整が発生することがあります。Not a lot of traffic at any one time, but enough over time that you run in and out of throttling in an episodic way.

    • たとえば、ファイルを SharePoint Online へ移行した後に、ファイルのメタデータを更新するカスタム CSOM または REST スクリプトを実行するとします。CSOM/REST スクリプトは多数のファイルを非常に高い頻度で更新するため、調整が発生します。同様に、REST サービスを使用するオートコンプリート UI ウィジェットは、各エンド ユーザー操作中にリストの呼び出しを多数実行するため、同時にリソースを消費するその他の操作によっては、調整が発生することがあります。For example, after migrating files to SharePoint Online, you run a custom CSOM or REST script to update metadata on the files. The CSOM/REST script is updating a large number of files at a very high frequency, which triggers throttling. Similarly, an autocomplete UI widget using REST services, making too many calls to lists during each end user operation, may also cause throttling, depending on what other operations are consuming resources at the same time.

    散発的調整

  • 圧倒的な大量トラフィックOverwhelming traffic

    1 つのプロセスが、長期にわたって継続的に調整制限を大幅に超過します。A single process dramatically exceeds throttling limits, continually, over a long time period.

    • Web サービスを使用して、ユーザー プロファイル プロパティを同期するツールを作成したとします。このツールは、基幹業務 (LOB) 人事 (HR) システムの情報に基づいてユーザー プロファイルのプロパティを更新します。このツールが呼び出しを実行する頻度が高すぎます。You used web services to build a tool to synchronize user profile properties. The tool updates user profile properties based on information from your line-of-business (LOB) human resources (HR) system. The tool makes calls at too high a frequency.

    • SharePoint Online でロード テスト用のスクリプトを実行すると、調整が生じます。SharePoint Online ではロード テストはできません。You're running a load-testing script on SharePoint Online and you get throttled. Load testing is not allowed on SharePoint Online.

    • SharePoint Online のチーム サイトをカスタマイズし、ステータス インジケーターをホーム ページに追加しました。このステータス インジケーターが頻繁に更新されて、そのページで SharePoint Online サービスに対する呼び出しが多くなりすぎ、調整が発生します。You customized your team site on SharePoint Online, for example, by adding a status indicator on the Home page. This status indicator updates frequently, which causes the page to make too many calls to the SharePoint Online service - this triggered throttling.

    規則的調整

正確な調整制限を設定できない理由Why can't you just tell me the exact throttling limits?

調整制限を設定して公表するということは容易に聞こえますが、実際には最良の方法ではありません。SharePoint Online でのリソース使用状況を継続的に監視しており、SharePoint Online のパフォーマンスと信頼性を損なわずにユーザーが最大数のリソースを使用できるように、使用状況に応じて調整を細かく調整しています。この点から、調整に対応するため、CSOM コードと REST コードに増分バックオフを組み込むことが非常に重要なのです。これによりコードはいつでも可能な限り高速に実行され、調整制限に達するとコードは「過不足のない」状態にバックオフできます。この記事の後半に、増分バックオフの使用法を示すコード サンプルが記載されています。Setting and publishing exact throttling limits sounds very straightforward, but in fact, it's not the best way to go. We continually monitor resource usage on SharePoint Online. Depending on usage, we fine-tune thresholds so users can consume the maximum number of resources without degrading the reliability and performance of SharePoint Online. That's why it's so important for your CSOM or REST code to include incremental back off to handle throttling; this lets your code run as fast as possible on any given day, and it lets your code back off "just enough" if it hits throttling limits. The code samples later in this article show you how to use incremental back off.

調整に対応するためのベスト プラクティスBest practices to handle throttling

  • 要求あたりの操作数を削減するReduce the number of operations per request

  • 呼び出しの頻度を減らすReduce the frequency of calls

  • ユーザーがわかるように、トラフィックを装飾する (後述のトラフィックを装飾するためのベストプラクティスを参照)Decorate your traffic so we know who you are (see section on traffic decoration best practice more on that below)

調整が発生している場合は、これ以上調整が発生しなくなるまで、増分バックオフを使用して呼び出しの数と頻度を減らすことをお勧めします。If you do run into throttling, we recommend incremental back off to reduce the number and frequency of calls until no more throttling occurs.

増分バックオフは、調整されたコードを再度実行するまで、再試行のたびに徐々に長くなる待機を使用します。この記事で後述する GitHub コード サンプルを使用できます。このコード サンプルはコードに増分バックオフを追加する拡張メソッドとして作成されています。Incremental back off uses progressively longer waits between retries before trying again to run the code that was throttled. You can use the GitHub code samples, later in this article, written as extension methods, to add incremental back off to your code.

バックオフは調整に対処する最速の方法ですが、それはユーザーが調整されている間に SharePoint Online がリソース使用量のログへの記録を続けるためです。つまり、呼び出しが失敗しても使用制限に対して加算されることに変わりはないため、積極的な再試行は不利に働きます。バックオフが早ければ早いほど、使用制限の超過を早く止めることができます。Backing off is the fastest way to handle being throttled because SharePoint Online continues to log resource usage while a user is being throttled. In other words, aggressive retries work against you because even though the calls fail, they still accrue against your usage limits. The faster you back off, the faster you'll stop exceeding usage limits.

SharePoint Online アクティビティの監視方法について詳しくは、「 Diagnosing performance issues with SharePoint Online」をご覧ください。For information about ways to monitor your SharePoint Online activity, see Diagnosing performance issues with SharePoint Online.

Microsoft Cloud における調整についてのより幅広い議論については「調整パターン」を参照してください。For a broader discussion of throttling on the Microsoft Cloud, see Throttling Pattern.

調整を回避するために、http トラフィックを装飾する方法How to decorate your http traffic to avoid throttling?

高い可用性の維持のため、一部のトラフィックが制限される可能性があります。To ensure and maintain high-availability, some traffic may be throttled. 調整はシステムの健全性が危険にさらされている場合に発生します。調整で使用する要件のひとつとしてトラフィックの装飾があります。これはトラフィックの優先度決定に直接影響を与えます。Throttling happens when system health is at stake and one of the criteria used for throttling is traffic decoration, which impacts directly on the prioritization of the traffic. 適切に装飾されたトラフィックは、不適切な装飾を施したトラフィックより優先されます。Well decorated traffic will be prioritized over traffic which is not properly decorated.

装飾されていないトラフィックの定義は?What is definition of undecorated traffic?

  • SharePoint Online への CSOM または REST API 呼び出しに、AppID/AppTitle および User Agent 文字列がない場合は、非装飾のトラフィックです。Traffic is undecorated if there is no AppID/AppTitle or User Agent string in CSOM or REST API call to SharePoint Online. User Agent 文字列は、次のように、特定の形式になっている必要があります。The User Agent string should be in a specific format as described below.

推奨事項は何ですか?What are the recommendation?

  • アプリケーションを作成した場合、AppID と AppTitle を登録して使用するようお勧めします。これにより、総合的なエクスペリエンスが向上し、今後の問題解決のための最善の道筋が確立されます。If you have created an application, recommendation is to register and use AppID and AppTitle – This will ensure the best overall experience and best path for any future issue resolution. また、次の手順に従い、User Agent 文字列情報も使用してください。Include also the User Agent string information as defined in following step.

  • SharePoint への API の呼び出しに、次の命名規則に従った User Agent 文字列を必ず含めてください。Make sure to include User Agent string in your API call to SharePoint with following naming convention

種類Type ユーザー エージェントUser Agent 説明Description
ISV ApplicationISV Application ISV|CompanyName|AppName/VersionISV|CompanyName|AppName/Version ISV を指定し、会社名、アプリ名をパイプ文字で区切り、その後ろにスラッシュで分離してバージョン番号を追加します。Identify as ISV and include Company Name, App Name separated by a pipe character and then adding Version number separated with a slash character
エンタープライズ アプリケーションEnterprise application NONISV|CompanyName|AppName/VersionNONISV|CompanyName|AppName/Version NONISV を指定し、会社名、アプリ名をパイプ文字で区切り、その後ろにスラッシュで分離してバージョン番号を追加します。Identify as NONISV and include Company Name, App Name separated by a pipe character and then adding Version number separated with a slash character
  • SharePoint Online API を呼び出すための自前の JavaScript ライブラリを構築している場合は、http 要求にユーザー エージェント情報を付加していることを確認してください。また、適切な場所で、使用する Web アプリケーションをアプリケーションとしても登録することを検討してください。If you are building your own JavaScript libraries, which are used to call SharePoint Online APIs, make sure that you include the User Agent information to your http request and potentially register your web application also as an Application, where suitable.

注意

ユーザー エージェント文字列の形式は RFC2616 に従ったものとします。よって、この勧告に従った右の区切り文字を使用してください。Format of the user agent string is expected to follow RFC2616, so please follow up on the above guidance on the right separators. 要求された情報のやりとりにも既存のユーザー エージェント文字列を付加することができます。It is also fine to append existing user agent string with the requested information.

注意

ブラウザーで実行中のフロント エンド コンポーネントを開発している場合、最新のブラウザーのほとんどはユーザー エージェント文字列の上書きを許可していないので、この機能を実装する必要はありません。If you are developing front end components executing in the browser, most of modern browsers don't allow overwritting the user agent string and you don't need to implement this.

クライアント側オブジェクト モデル (CSOM) を使用した場合で、ユーザー エージェントを使いトラフィックを装飾する例Example of decorating traffic with User agent when using Client Side Object Model (CSOM)

// Get access to source site
using (var ctx = new ClientContext("https://contoso.sharepoint.com/sites/team"))
{
    //Provide account and pwd for connecting to SharePoint Online
    var passWord = new SecureString();
    foreach (char c in pwd.ToCharArray()) passWord.AppendChar(c);
    ctx.Credentials = new SharePointOnlineCredentials("contoso@contoso.onmicrosoft.com", passWord);

    // Add our User Agent information
    ctx.ExecutingWebRequest += delegate (object sender, WebRequestEventArgs e)
    {
        e.WebRequestExecutor.WebRequest.UserAgent = "NONISV|Contoso|GovernanceCheck/1.0";
    };

    // Normal CSOM Call with custom User-Agent information
    Web site = ctx.Web;
    ctx.Load(site);
    ctx.ExecuteQuery();
}

REST API を使用した場合で、ユーザー エージェントを使いトラフィックを装飾する例Example of decorating traffic with User agent when using REST APIs

次の例は、C# の形式ですが、SharePoint Online のページで使用されている JavaScript ライブラリに対しても、同様のユーザー エージェント情報の使用をお勧めします。Following sample is in c# format, but the similar User Agent information is recommended to be used even for the JavaScript libraries used in the SharePoint Online pages.

HttpWebRequest endpointRequest = (HttpWebRequest)HttpWebRequest.Create(sharepointUrl.ToString() + "/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.UserAgent = "NONISV|Contoso|GovernanceCheck/1.0";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization", "Bearer " + accessToken);
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

GitHub CSOM コード サンプル: SharePoint Online の調整GitHub CSOM code samples: SharePoint Online Throttling

Office 365 デベロッパー パターンとプラクティスのリポジトリCoreThrottling は、増分バックオフの技法を示すコード サンプルです。この技法では、必要なコード変更を最小限にとどめることができます。CoreThrottling in the Office 365 Developer Patterns and Practices repository is a code sample that demonstrates the incremental back off technique. The technique requires minimal changes to your code.

このコード サンプルを実行する前に、次の操作を実行してください。Before you run this code sample:

  • Program.cs を開き、 Main メソッドに次の情報を入力します。Open Program.cs and enter the following information in the Main method:

    • Office 365 開発者アカウントの資格情報Your Office 365 Developer account credentials.

    • Office 365 開発者向けサイトの URLThe URL of your Office 365 Developer Site.

    • Office 365 開発者向けサイトにあるテスト ドキュメント ライブラリの名前The name of a test document library on your Office 365 Developer Site.

  • App.Config ファイルが無効というエラーが出る場合は、 ソリューション エクスプローラーApp.config を右クリックし、[ プロジェクトから除外 ] を選択してください。If you receive an error stating that the App.Config file is invalid, go to Solution Explorer, right click App.config, and choose Exclude From Project.

ユーザーのみ承認ポリシーを使用するコンソール アプリケーションとして Core.Throttling が実行される場合、このコード サンプルは、現在のユーザーのアクセス許可を使用することになります。Program.cs の Main メソッドでは、while ループを使用してテスト ドキュメント ライブラリに新しいフォルダーが繰り返し作成されます。その後、 ctx.ExecuteQueryWithExponentialRetry が呼び出され、CSOM を使用して ExecuteQuery メソッドが実行されます。 ExecuteQueryWithExponentialRetry は、 ClientContext オブジェクトの拡張メソッドであり、 ClientContextExtension.cs 内で定義されています。Core.Throttling runs as a console application using a user-only authorization policy, which means this code sample uses the permissions of the current user. In the Main method in Program.cs, a while loop repeatedly creates new folders in the test document library. A call is then made to ctx.ExecuteQueryWithExponentialRetry, which uses CSOM to perform the ExecuteQuery method. ExecuteQueryWithExponentialRetry is an extension method on the ClientContext object, and is defined in ClientContextExtension.cs.

SharePoint Online が ExecuteQuery ステートメントを調整する場合、 ExecuteQueryWithIncrementalRetry により、次のようにして増分バックオフの技法が開始されます。If SharePoint Online throttles the ExecuteQuery statement, ExecuteQueryWithIncrementalRetry starts the incremental back off technique by:

  • WebException をキャッチし、 HttpWebResponse.StatusCode をチェックします。SharePoint Online が ExecuteQuery ステートメントを調整した場合は、 HttpWebResponse.StatusCode は 429 になります。Catching a WebException and checking the HttpWebResponse.StatusCode. If SharePoint Online throttled the ExecuteQuery statement, the HttpWebResponse.StatusCode is 429.

  • 現在のスレッドが、 backoffInterval で指定された時間だけ中断します。The current thread is suspended for the period specified in backoffInterval.

  • 現在のスレッドが再開されると、 backoffInterval が 2 倍に設定され、実行した再試行の数 ( retryAttempts ) がインクリメントされます。 backoffInterval が 2 倍になるため、SharePoint Online によって調整されたコードを再試行するまでコードが活動を中断する時間が長くなります。When the current thread resumes, the backoffInterval is doubled and the number of retries performed ( retryAttempts ) is incremented. By doubling backoffInterval your code suspends activity for a longer period of time before retrying the code that was throttled by SharePoint Online.

  • ExecuteQuery ステートメントが正常に実行されるか、または許容される試行回数 ( retryCount ) を超えるまで、この処理が繰り返されます。The process is repeated until either the ExecuteQuery statement is successful, or the number of allowed retries ( retryCount ) is exceeded.

CSOM コード サンプル: 増分バックオフと再試行 (この記事の後半に記載されている ExecuteQueryWithIncrementalRetry メソッドを呼び出す)CSOM Code sample: Incremental back off and retry (calls ExecuteQueryWithIncrementalRetry method, later in this article)


using (var ctx = new ClientContext(serverUrl))
       {
           //Provide account and pwd for connecting to the source
           var passWord = new SecureString();
           foreach (char c in password.ToCharArray()) passWord.AppendChar(c);
           ctx.Credentials = new SharePointOnlineCredentials(login, passWord);
            try
           {
               int number = 0;
               // This loop will be executed 1000 times, which will cause throttling to occur
               while (number < 1000)
               {
                   // Try to create new folder based on Ticks to the given list as an example process
                   var folder = ctx.Site.RootWeb.GetFolderByServerRelativeUrl(listUrlName);
                   ctx.Load(folder);
                   folder = folder.Folders.Add(DateTime.Now.Ticks.ToString());
                   // Extension method for executing query with throttling checks
                   ctx.ExecuteQueryWithIncrementalRetry(5, 30000); //5 retries, with a base delay of 30 secs.
                   // Status indication for execution.
                   Console.WriteLine("CSOM request successful.");
                   // For loop handling.
                   number = number + 1;
               }
           }
           catch (MaximumRetryAttemptedException mex)
           {
               // Exception handling for the Maximum Retry Attempted
               Console.WriteLine(mex.Message);
           }
       }

CSOM コード サンプル: ExecuteQueryWithIncrementalRetry メソッドCSOM Code sample: ExecuteQueryWithIncrementalRetry method


public static void ExecuteQueryWithIncrementalRetry(this ClientContext context, int retryCount, int delay)
        {
            int retryAttempts = 0;
            int backoffInterval = delay;
            if (retryCount <= 0)
                throw new ArgumentException("Provide a retry count greater than zero.");
           if (delay <= 0)
                throw new ArgumentException("Provide a delay greater than zero.");
           while (retryAttempts < retryCount)
            {
                try
                {
                    context.ExecuteQuery();
                    return;
                }
                catch (WebException wex)
                {
                    var response = wex.Response as HttpWebResponse;
                    if (response != null &amp;&amp; response.StatusCode == (HttpStatusCode)429)
                    {
                        Console.WriteLine(string.Format("CSOM request exceeded usage limits. Sleeping for {0} seconds before retrying.", backoffInterval));
                        //Add delay.
                        System.Threading.Thread.Sleep(backoffInterval);
                        //Add to retry count and increase delay.
                        retryAttempts++;
                        backoffInterval = backoffInterval * 2;
                    }
                    else
                    {
                        throw;
                    }
                }
            }
            throw new MaximumRetryAttemptedException(string.Format("Maximum retry attempts {0}, have been attempted.", retryCount));
       }

SharePoint Online でブロックが生じた場合の対処方法What should you do if you get blocked in SharePoint Online?

ブロックは、最も極端な形式の調整です。SharePoint Online サービスの全体的な正常性に深刻な影響を及ぼす可能性がある、長期にわたる非常に大量のトラフィックが発生している場合を除き、テナントをブロックすることは非常に稀です。ブロックは、非常に大量のトラフィックによって SharePoint Online のパフォーマンスと信頼性が低下することを防ぐために適用されます。通常テナンシー レベルで適用されるブロックは、問題が解決されるまでの間、問題のあるプロセスの実行を阻止します。サブスクリプションがブロックされる場合、問題のあるプロセスに変更を加えるための処置をとらないと、ブロックを除去できません。Blocking is the most extreme form of throttling. We rarely ever block a tenant, unless we detect long-term, extremely excessive traffic that may threaten the overall health of the SharePoint Online service. We apply blocks to prevent excessive traffic from degrading the performance and reliability of SharePoint Online. A block - which is usually placed at the tenancy level - prevents the offending process from running until you fix the problem. If we block your subscription, you must take action to modify the offending processes before the block can be removed.

サブスクリプションがブロックされると、HTTP ステータス コード 503 が表示され、Office 365 メッセージ センターでブロックされたことについて通知されます。このメッセージには、ブロックの原因、問題を解決するための方法のガイダンス、およびブロックを除去するための連絡先が記されています。If we block your subscription, you'll see HTTP status code 503, and we'll notify you of the block in the Office 365 Message Center. The message describes what caused the block, provides guidance on how to resolve the offending issue, and tells you who to contact to get the block removed.

関連項目See also