Salesforce が提供する API を利用するときに考慮する事項と FAQ

本ドキュメントでは、Salesforce が提供する Web API の利用を検討するときにご留意いただきたいトピックや、よくある問い合わせについて紹介します。

*HTTP Status Code が 500 番台で応答されることを、以後は 500 エラーと表記します。

<検討のポイント>
Point 1 : 自動でのリトライを実装する (重要)
API リクエストは一時的なエラーが応答される場合があります。その要因は API サービスの負荷やインターネットなど様々ですが、実際の利用では少なからず一時的なエラーの発生に遭遇します。そのため、このようなエラーが発生することをあらかじめ想定しておき、リトライの仕組みを必ず検討する必要があります。具体的には API リクエストを発行するアプリケーションで、エラーハンドリングの処理を追加します。そして、エラーが発生したときに適切な回数・タイミングで API リクエストのリトライを自動で行う仕組みを実装します。自動でのリトライを実装することで、 API サービスをより安定的に利用できます。

Point 2 : API クライアントでのタイムアウト時間の調整を検討する (中継機器を含む)
上記 Point1 に記載したものと同様、種々の要因により API リクエストの応答がなかなか得られない場合があります。このとき API クライアント 側で保持するタイムアウト時間が短すぎると、当社 API サービスから応答を待たずにアプリケーションが処理を終了してしまう可能性があります。これにより必要以上にエラー頻度が高くなる可能性があるため、このケースが頻繁に確認される場合、API クライアント側でのタイムアウト時間の調整を検討します。

なお、ここでいう API クライアントとは、API リクエストを発行するアプリケーションやサーバーのほか、経路上にある API の中継サーバーやネットワーク機器も含みます。アプリケーションのタイムアウトだけを延長しても、これら中継機器のタイムアウト時間のほうが短ければ、これらの機器からタイムアウトを応答してしまい、タイムアウトエラーの頻度が低減しない可能性があります。そのため、タイムアウトが発生している機器を確認して延長することが重要になります。

*当社 API サービスにおける具体的なタイムアウト時間については末尾の FAQ を参照してください。

Point 3 : 詳細なログを残す
API リクエストがエラーとなったことについての原因調査依頼の問い合わせをいただくことがあります。このとき、厳密な調査のためには、「API リクエスト/レスポンス」のデータが必要になります。よって API を利用する場合は詳細なリクエスト/レスポンスの情報の記録を取得することを検討します。

なお、SOAP API にて ExceptionCode が返却される場合や、REST API で HTTP Status Code 400 番台 (Bad Request) が発生したときは、リクエスト内容に問題がある可能性があります。当該リクエストに対するレスポンス Body 内には、問題のある個所が表示されていますので、まずはこちらを参照し、リクエストに問題がないか精査します。代表的なエラーの詳細は以下の参考情報配下の Document に補足がありますので、合わせてご参照ください。もしリクエストに問題が見受けられず、サポートケースを起票する場合はリクエストとレスポンスの情報をご提供ください。

※このとき、API クライアント上で稼働する独自のアプリケーションのログを寄せていただくことがあります。Salesforce が応答するリクエスト/レスポンスの情報が含まれない場合、正しく調査できない可能性があります。

参考情報:
・SOAP API - API コールで使用されるコアデータ型
・REST API - 状況コードとエラー応答

<問い合わせするときの提供推奨情報>
API リクエストのエラー発生について調査の依頼をいただく場合は、以下の情報を添えてください。
複数発生した場合は、同じエラーについて代表的なものを 2-3 件程度サンプリングいただく形で構いません。

・エラーが発生した組織の組織 ID
・API の実行ユーザー (ユーザー名)
・API 種別 (REST API, SOAP API 等)
・リクエスト日時 (JST)
・リクエスト URL、メソッド
・リクエスト Body
・レスポンス Body

また、500 エラーが連続して多数回発生した場合、リクエストの内容に依存しない場合があるため、下記の情報でも構いません。

・エラーが発生した組織の組織 ID
・API の実行ユーザー (ユーザー名)
・API 種別 (REST API、SOAP API 等)
・エラーが確認された時間帯 (JST)
・エラーのおおよその頻度 (例 : 3 分間に 10 リクエスト中 8 回発生など)
・詳細な処理内容（例：SOAP APIのメソッド名（query() など）、REST API のエンドポイント URL など）
・そのほか、エラーの詳細がわかる情報 (レスポンス Body、API クライアントのアプリ上のログ、SOQL など)

※ 異なる種別のエラーが発生している場合、複数のお問い合わせに分けてご連絡をいただくことで、複数のエンジニアにて並行して調査が可能です。

<問い合わせでよく発生する状況：エラー数の差異>
API クライアントで発生したエラー内容/回数と、当社が記録しているログ上から確認できるエラー内容/回数とに差異がある場合があります。

例 :
API クライアントで確認された 500 エラー数 = 10 回
当社で記録された 500 エラー数 = 0 回

このケースでは、上記 Point 2 の通り経路上にある中継機器/アプリケーションなどで直接エラーを発生させている可能性があります。そのため、エラーを発生させている機器で詳細を確認する必要があります。

<FAQ>
Q) 500 エラー が応答される原因は?
A) 多岐にわたります。500 エラーはサーバー上のエラーと定義されますが、外部要因により正常に応答できない場合にも発生します。

500 エラーが連続して多数発生する場合、当社のサービスで何らかの問題が発生している可能性があります。このような状況では、Trust サイトを確認し、インシデントやメンテナンス等の情報をチェックしてください。

一方で、頻度が低く散発的に発生する場合、当社側で取得できるログのみで問題の特定に至ることは難しいケースも多いことをあらかじめご了承ください。ログに特定の問題を示さなくともこのエラーが応答されるケース、弊社 API サーバーでは 500 エラーを応答しておらず、お客様環境の機器がタイムアウトなどにより代理で応答しているケースなどさまざまな要因があります。

また、このような散発的なエラーの遭遇は問題の特定ができたとしても、ゼロにすることは困難です。しかしながらほとんどの場合で少し時間をおいてリトライすることでカバーできるため、リトライの仕組みが重要になります。このため 1 つ 1 つの一時的な 500 エラーに関して個別に原因を追究するよりも、リトライをいかに効率よく行うか検討を行うことが安定的な利用にとって極めて重要です。

* これは API に限らず Web を経由するあらゆる通信に共通します。

Q) 推奨されるリトライ方式はありますか?
A) 当社が基準として掲示しているものはありません。例としてあげるなら、一定間隔で複数回実行する (例 : 15 秒間隔で 3 回)、徐々に実行間隔を大きくしていく (例 : 3 秒後、10 秒後、60 秒後…) などの方式が考えられます。

Q) リクエスト数上限やタイムアウトなどの制限について確認したい
A) 下記参考 1 のドキュメントにリクエスト数上限やタイムアウトに関する制限が記載されています。

この制限のほか、負荷の大きなリクエストを短時間に多数実行していると、一時的に制限がかかる場合があるため注意してください。
具体的には下記参考 2 のドキュメントの通り、当社サービスのパフォーマンスへ悪影響を与えてしまう程度のリクエストを行った場合、一時的に制限 (スロットル) されます。これが頻発する場合、リクエスト頻度を下げる、処理内容を見直すなどを検討してください。他に、API 要求ごとにログインコールを行うような処理となっている場合、下記参考 3 のドキュメントにある一定時間内のログイン数制限に抵触しやすくなるため、セッションを再利用するような処理を検討します。

参考 1) API 要求の制限と割り当て
参考 2) スロットルが私の組織に適用されている/適用された
参考 3) サインインエラー: 「ログイン数超過」

Q) API クライアントの利用方法に関する質問 (API 実行ツールの利用方法やコマンドなど)、各 API クライアントに適合するリクエストのサンプル提供依頼 (ドキュメントにない Python やCurl 等でのコードサンプルなど) について
A) これらは当社製品に依存しない部分のため、サポートケースでは基本的には正式に回答していません。もし製品に依存する問題と見受けられる内容でしたら、切り分け結果などを添えて問い合わせてください。