SOAP API 開発者ガイド
j実装に関する考慮事項
この章では、インテグレーションアプリケーションをはじめとするアプリケーションを開発する前に考慮すべき、データ管理、使用制限、通信などの課題について説明します。
インテグレーション用のユーザの選択
クライアントアプリケーションが API に接続するとき、最初にログインする必要があります。login() コール時には Salesforce にログインするためのユーザを指定する必要があります。クライアントアプリケーションは、ログインユーザの権限および共有設定に基づいて動作します。以降のセクションでは、クライアントアプリケーション用のユーザを構成する方法について説明します。
権限
組織の Salesforce 管理者は、プロファイルおよび権限セットを設定し、ユーザをそれらに割り当てることによって、さまざまな機能やビューの使用を制御します。API にアクセスするには (コールを発行してコール結果を受信するには)、ユーザに「API 対応」権限が割り当てられている必要があります。クライアントアプリケーションは、ログインユーザの権限を介してアクセス権限を付与されるこれらのオブジェクトおよび項目のみを照会したり更新したりできます。
共有ルールによってデータへのアクセスを許可されたユーザとしてのログインでは、API はアクセスを確認する追加のクエリを発行する必要があります。それを避けるには、「すべてのデータの編集」権限を持つユーザとしてログインします。これによって、コールの応答時間を短縮できます。「すべてのデータの編集」権限を許可すると、特定のユーザには権限範囲が広すぎることがあります。その場合は、オブジェクトレベルの権限である「すべて変更」を使用して、データのアクセスをオブジェクト単位に制限することを検討してください。権限の詳細は、「データアクセスに影響する要素」を参照してください。
ログインサーバの URL
API の SOAP 実装は、単一のログインサーバを提供します。組織のインスタンスをハードコード化することなく、単一のエントリポイントからどの組織へもログインできます。API を介して組織にアクセスするには、まず、選択した WSDL に応じて次のどちらかの URL にあるログインサーバに login() 要求を送信し、セッションの認証を受けます。
- https://login.salesforce.com/services/Soap/c/44.0 (Enterprise WSDL)
- https://login.salesforce.com/services/Soap/u/44.0 (Partner WSDL)
セキュリティのより低い URL もサポートされています。
1http://login.salesforce.com/services/Soap/c/44.0- http://login.salesforce.com/services/Soap/c/44.0 (Enterprise WSDL)
- http://login.salesforce.com/services/Soap/u/44.0 (Partner WSDL)
よりセキュリティの低い URL もサポートしていますが、お勧めできません。プロキシサーバ経由でデバッグする場合に役立ちます。
セッション中のすべての後続コールは、login() のレスポンスで返された URL に対して実行する必要があります。この URL は組織のサーバインスタンスを示しています。
ログインサーバへのログイン
クライアントアプリケーションは、他のコールを呼び出す前にまず login() コールを呼び出してログインサーバとのセッションを確立し、返されたサーバの URL を後続の API 要求の要求先サーバとして設定し、返されたセッション ID を SOAP ヘッダーに設定して後続の API 要求のサーバ認証が行えるようにする必要があります。詳細は、「login()」 および「ステップ 4: サンプルコードを説明する」を参照してください。
Salesforce は、クライアントアプリケーションがログインしている IP アドレスを確認し、不明な IP アドレスからのログインをブロックします。API 経由でブロックされたログインに関しては、Salesforce がログイン失敗エラーを返します。この場合、ユーザはログインパスワードにセキュリティトークンを追加する必要があります。セキュリティトークンは Salesforce から自動生成されるキーです。たとえば、パスワードが mypassword で、セキュリティトークンが XXXXXXXXXX の場合は、ログイン時に「mypasswordXXXXXXXXXX」と入力する必要があります。セキュリティトークンを取得するには、Salesforce ユーザインターフェースを通じてパスワードを変更するか、セキュリティトークンをリセットします。ユーザがパスワードを変更するか、セキュリティトークンをリセットすると、ユーザの Salesforce レコードに指定されたメールアドレス宛に新しいセキュリティトークンが送信されます。セキュリティトークンは、ユーザがセキュリティトークンをリセットするか、パスワードを変更するか、またはパスワードをリセットするまで有効です。セキュリティトークンが無効である場合、ユーザはログインプロセスを繰り返さなければなりません。このような事態を避けるには、システム管理者が組織の所有する信頼できる IP アドレスの一覧にクライアントの IP アドレスが追加されていることを確認する必要があります。詳細は、「セキュリティトークン」を参照してください。
ログイン後は、API コールを実行できます。それぞれの操作に対し、クライアントアプリケーションは同期要求を API に送信し、レスポンスを待ち、結果を処理します。API は変更されたデータすべてを自動的にコミットします。
API コールには、次のようなものがあります。
一般的な API コールシーケンス
各コールに対し、クライアントアプリケーションは一般的に次の処理を行います。
- パラメータを使用する場合、要求パラメータを定義して要求の準備を行います。
- 要求とパラメータを Lightning Platform Web サービスに渡し処理するためにコールを呼び出します。
- API からのレスポンスを受け取ります。
- 返されたデータを処理するか (呼び出しが成��した場合)、エラーを処理し (呼び出しが失敗した場合)、レスポンスを処理します。
Salesforce Sandbox
Professional Edition、Enterprise Edition、Unlimited Edition、および Performance Edition を使用している場合、Salesforce Sandbox にアクセスできます。これは、Salesforce 組織の本番データの全部または一部の複製を提供するテスト環境です。Salesforce Sandbox についての詳細は、Salesforce コミュニティの Web サイト (www.salesforce.com/community) にアクセスするか、Salesforce ヘルプの「Sandbox の種別およびテンプレート」を参照してください。
API を介して組織の Salesforce Sandbox にアクセスするには、次の URL からログイン要求を行います。
- https://test.salesforce.com/services/Soap/c/44.0 (Enterprise WSDL)
- https://test.salesforce.com/services/Soap/u/44.0 (Partner WSDL)
API 通信量の監視
組織で生成された API 要求の数を監視するには、次の 2 つの方法があります。
- すべてのユーザが 24 時間以内に送信された API 要求の数を確認できます。情報を表示するには、[設定] から、[クイック検索] ボックスに「組織情報」と入力し、[組織情報] を選択します。右の列の [API 要求数 (この 24 時間以内)] を参照します。
- ユーザが「すべてのデータの編集」権限を持つ場合、7 日以内に送信された API 要求のレポートを参照できます。情報を参照するには、[レポート] タブをクリックし、[管理レポート] セクションにスクロールして [過去 7 日間の API 使用状況] リンクをクリックします。[集計情報:] ドロップダウンリストにある任意の項目でレポートを並び替えることができます。レポートの並び替え、絞り込み、カスタマイズの詳細は、Salesforce オンラインヘルプのレポートについての記述を参照してください。
API 使用状況の測定
最適なパフォーマンスを維持し、すべてのお客様が Lightning Platform API を使用できるようにするために、Salesforce は次の 2 つ種類の制限を設けることによって、トランザクションの負荷を調整しています。
- 同時 API 要求数の制限
- 合計 API 要求の割り当て
同時 API 要求数の制限
次の表は、20 秒以上の同時要求 (コール) 数について、さまざまな種類の組織に対する制限を示しています。
合計 API 要求の割り当て
次の表は、組織の 24 時間あたりの API 要求 (コール) 数の合計に関する制限について示しています。
コール数の制限は、24 時間あたりに組織で行われた API コール数の集計に対して適用されます。この制限は、ユーザごとに適用されるものではありません。組織がこの制限を超過した場合、組織内のすべてのユーザが一時的にブロックされ、追加のコールを行うことができなくなります。直近 24 時間の使用状況が制限値内に収まるまで、コールはブロックされます。
API にコールを送信するアクションはすべて、次の場合を除いて使用量に数えられます。
- アウトバウンドメッセージ
- Apex コールアウト
API の使用状況についての通知を作成することができます。これにより、Salesforce は定義された時間内の API の上限を超えたときに、事前に定義されたユーザにメールを送信します。詳細は、Salesforce オンラインヘルプの「API 使用状況通知」を参照してください。
Salesforce ユーザインターフェースからの組織あたりの要求数の上限もあります。詳細は、Salesforce オンラインヘルプの「同時使用制限」を参照してください。
API 使用制限の計算例
- Salesforce ライセンスを 15 個割り当てられている Enterprise Edition 組織の場合、要求数の制限は 15,000 件です (15 個のライセンス X 1,000 件のコール)。
- Salesforce ライセンスが 15,000 件割り当てられている Enterprise Edition 組織の場合、要求数の制限は 1,000,000 件です (ライセンスの数 X 1,000 コールが最大値より大きいため、下限の 1,000,000 が使用されます)。
- 水曜日の午前 5 時に 14,500 件のコールが作成され、水曜日の午後 11 時に 499 件のコールが作成された Developer Edition の場合、木曜日の午前 5 時まで正常に作成できるコール数はあと 1 件だけです。
- Gold Partner ライセンスが 60 件割り当てられている Enterprise Edition 組織の場合、要求数の制限は 15,000 件です (ライセンスの数 X 200 コールが最小値の 15,000 より少ないため)。
API 要求数の合計に対する制限の増加
ユーザライセンスに基づく API 要求数の制限の計算は、ユーザ数に基づいて組織に十分な利用可能数を許可するよう意図されています。制限を引き上げる必要があるものの、ユーザライセンスの追加購入や Performance Edition へのアップグレードを希望しない場合は、API コールを追加購入できます。詳細は、営業担当者にお問い合わせください。
API コールを追加購入する前に、現在の API 使用状況を精査する必要があります。API に対するコールを行うクライアントアプリケーションが、独自のエンタープライズアプリケーションであってもパートナーアプリケーションであっても、最適化によって、同じ処理を行うのに使用する API コールを減らせる場合がしばしばあります。パートナー製品をお使いの場合、供給メーカーにお問い合わせいただき、その製品での API の使用が最適化されていることを確認してください。API の使用効率のよくない製品は、組織に不要なコストを負わせることになります。
圧縮
API は、HTTP 1.1 の仕様で定義された標準を使用した要求とレスポンスの圧縮をサポートしています。いくつかの SOAP/WSDL クライアントでは自動的にサポートされており、他のクライアントへも手動で追加できます。クライアント別の詳細は、https://developer.salesforce.com/page/Tools を参照してください。
圧縮は、クライアントが明示的に指定しない限り使用されません。パフォーマンス向上のため、HTTP 1.1 の仕様に従ったクライアント側での圧縮のサポートをお勧めします。
クライアントが圧縮をサポートしていることを示すには、HTTP ヘッダー「Accept-Encoding: gzip, deflate」または同様のヘッダーを含める必要があります。クライアントのヘッダーで正しく指定されている場合、API はレスポンスを圧縮します。レスポンスには、「Content-Encoding: deflate」または「Content-Encoding: gzip」のいずれか適切な方が含まれます。「Content-Encoding: deflate」または「gzip」をヘッダーに含めることで、あらゆる要求を圧縮することができます。
ほとんどのクライアントは、たとえ企業内 LAN を使用している場合も、ある程度のネットワーク接続の制限があります。API は圧縮をサポートすることでパフォーマンスを向上します。ほとんどすべてのクライアントでは、レスポンスを圧縮することのメリットがあり、多くのクライアントでは要求の圧縮でもメリットがあります。API は HTTP 1.1 の仕様に従い deflate と gzip 圧縮をサポートします���
レスポンスの圧縮
API は、必要に応じてレスポンスを圧縮することができます。 クライアント側から Accept-Encoding ヘッダーで gzip または deflate 圧縮を指定した場合、レスポンスは圧縮されます。Accept-Encoding が指定された場合でも API ではレスポンスを圧縮する必要はありませんが、通常は圧縮されます。API がレスポンスを圧縮した場合、API は使用した圧縮アルゴリズムの名前で Content-Encoding ヘッダーも指定します (gzip または deflate のいずれか)。
要求の圧縮
クライアントは要求を圧縮することもできます。API は、処理前にすべての要求を展開します。クライアントは、適切な圧縮アルゴリズムの名前を記した Content-Encoding HTTP ヘッダーを送信しなければなりません。詳細は、以下を参照してください。
- Content-Encoding については、www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11
- Accept-Encoding については、www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
- Content Coding については、www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.5
HTTP 永続接続
ほとんどのクライアントでは、HTTP 1.1 の永続接続を使用し、複数の要求のソケット接続を再利用したほうがパフォーマンスが向上します。永続接続は通常 SOAP/WSDL クライアントが自動的に処理します。詳細は、次の HTTP 1.1 の仕様を参照してください。
http://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.1
国際化と文字コード
API は Unicode または ISO-8859-1 のいずれかの文字を完全にサポートしています。組織の使用する文字コードは、組織が使用している Salesforce インスタンスにより異なります。組織が ssl.salesforce.com にログインする場合、エンコードは ISO-8859-1 です。その他のすべてのインスタンスは UTF-8 を使用します。 describeGlobal() をコールし、DescribeGlobalResult に返された encoding 値を確認することで、組織の文字セットを確認できます。
組織で ISO-8859-1 エンコーディングを使用している場合、API に送信されるすべてのデータを ISO-8859-1 で符号化する必要があります。有効な ISO-8859-1 の範囲外の文字は、切り捨てられるか、エラーとなります。
XML 準拠
API は XML をベースとしています。XML では、すべてのドキュメントが正しい形式であることが求められます。その要件の一部には、エスケープ文字などを使用してもある特定の Unicode 文字は XML ドキュメントでは許可されないと定められています。また、その他の文字も地域に応じたエンコードが必要です。通常、標準 SOAP クライアントまたは XML クライアントが処理します。クライアントは、一般的な XML エスケープシーケンスすべてを解析する機能を持ち、無効な XML 文字を渡さないようにする必要があります。
前述のとおり、文字によってはエスケープ文字などを使用していても無効です。無効な文字には、ペアになっていない Unicode サロゲートやその他のいくつかの Unicode 文字が含まれます。これらの文字は滅多に使用されず、どのデータでも通常は重要視されない制御文字であるため、多くのプログラムで問題となる場合があります。これらの文字は XML ドキュメントでは許可されていませんが、HTML ドキュメントでは許可されており、Salesforce データにも含まれている場合があります。無効な文字は、すべての API レスポンスから除外されます。
無効な文字:
- 0xFFFE
- 0xFFFF
- 制御文字 0x0 から 0x19。ただし、有効な次の文字を除く。0x9、0xA、0xD、タブ、改行、キャリッジリターン。
- 0xD800 - 0xDFFF、サロゲートペアを形成するために使用されている場合を除く
.NET、非文字列項目、および Enterprise WSDL
.NET と Enterprise WSDL を共に使用した場合、.NET は各非文字列項目に Boolean 型の項目を生成します。たとえば、MyDateField__c に日付値がある場合、.NET は MyDateField__cSpecified と呼ばれる Boolean 型の項目を生成します。
生成される項目値は、デフォルトでは false です。指定された項目値が false である場合、対応する元の項目の値は SOAP メッセージには含まれません。たとえば、通貨項目 annualRevenue の値をクライアントアプリケーションが生成した SOAP メッセージに含める前に、annualRevenueSpecified の値を true に設定する必要があります。
1account.annualRevenue = 10000;
2account.annualRevenueSpecified = true;