実装に関する考慮事項

クライアントアプリケーションが API に接続するとき、最初にログインする必要があります。login() コール時には Salesforce にログインするためのユーザを指定する必要があります。クライアントアプリケーションは、ログインユーザの権限および共有設定に基づいて動作します。以降のセクションでは、クライアントアプリケーション用にユーザを構成する方法について説明します。

SOAP API は、単一のログインサーバを提供します。インスタンスをハードコード化することなく、単一のエントリポイントからどの組織へもログインできます。API を介して組織にアクセスするには、まず、選択した WSDL に応じて次のどちらかの URL にあるログインサーバに login() 要求を送信し、セッションの認証を受けます。

• https://login.salesforce.com/services/Soap/c/47.0 (Enterprise WSDL)
• https://login.salesforce.com/services/Soap/u/47.0 (Partner WSDL)

セキュリティのより低い URL もサポートされています。

• http://login.salesforce.com/services/Soap/c/47.0 (Enterprise WSDL)
• http://login.salesforce.com/services/Soap/u/47.0 (Partner WSDL)

よりセキュリティの低い URL もサポートしていますが、お勧めできません。プロキシサーバ経由でデバッグする場合に役立ちます。

セッション中のすべての後続コールは、login() のレスポンスで返された URL に対して実行する必要があります。この URL は組織のサーバインスタンスを示しています。

クライアントアプリケーションは、他のコールを呼び出す前にまず login() コールを呼び出してログインサーバとのセッションを確立する必要があります。次に、返されたサーバの URL を後続の API 要求の要求先サーバとして設定し、返されたセッション ID を SOAP ヘッダーに設定して後続の API 要求のサーバ認証が行えるようにする必要があります。Salesforce は、クライアントアプリケーションがログインしている IP アドレスを確認し、不明な IP アドレスからのログインをブロックします。詳細は、「login()」 および「ステップ 4: サンプルコードを説明する」を参照してください。

API でブロックされたログインに関しては、Salesforce がログイン失敗エラーを返します。ログインするには、ユーザがセキュリティトークンをユーザパスワードの末尾に追加する必要があります。たとえば、パスワードが mypassword で、セキュリティトークンが XXXXXXXXXX の場合は、「mypasswordXXXXXXXXXX」と入力する必要があります。セキュリティトークンを取得するには、Salesforce ユーザインターフェースからパスワードを変更するか、セキュリティトークンをリセットします。ユーザがパスワードを変更するか、セキュリティトークンをリセットすると、ユーザの Salesforce レコードに指定されたメールアドレス宛に新しいセキュリティトークンが送信されます。セキュリティトークンは、ユーザがセキュリティトークンをリセットするか、パスワードを変更するか、またはユーザのパスワードがリセットされるまで有効です。トークンが無効な場合、ユーザはログインプロセスを再度行う必要があります。再度ログインを行わないようにするには、クライアントの IP アドレスを組織の信頼できる IP アドレスのリストに追加します。詳細は、「セキュリティトークン」を参照してください。

ログイン後は、API コールを実行できます。それぞれの操作に対し、クライアントアプリケーションは同期要求を API に送信し、レスポンスを待ち、結果を処理します。API は変更されたデータを自動的にコミットします。

API コールには、次のようなものがあります。

• 基本となる API コール
• 記述用の API コール (describe)
• ユーティリティ API コール

各コールに対し、クライアントアプリケーションは一般的に次の処理を行います。

1. パラメータを使用する場合、要求パラメータを定義して要求の準備を行います。
2. 要求とパラメータを Lightning Platform Web サービスに渡し処理するためにコールを呼び出します。
3. API からのレスポンスを受け取ります。
4. 返されたデータを処理するか (呼び出しが成功した場合)、エラーを処理し (呼び出しが失敗した場合)、レスポンスを処理します。

Professional Edition、Enterprise Edition、Unlimited Edition、および Performance Edition を使用している場合、Salesforce Sandbox にアクセスできます。これは、Salesforce 組織の本番データの全部または一部の複製を提供するテスト環境です。詳細は、Salesforce コミュニティの Web サイト (www.salesforce.com/community) にアクセスするか、Salesforce ヘルプの「Sandbox の種別およびテンプレート」を参照してください。

API を介して組織の Sandbox にアクセスするには、次の URL からログイン要求を行います。

• https://test.salesforce.com/services/Soap/c/47.0 (Enterprise WSDL)
• https://test.salesforce.com/services/Soap/u/47.0 (Partner WSDL)

通常組織は地理的な地域ごとに分けられていますが、組織はあらゆるインスタンスに置かれる可能性があります。

API バージョン 7.0 以降では、すべての要求には Content-Type: text/xml; charset=utf-8 などの正しいコンテンツタイプの HTTP ヘッダーを含んでいなければなりません。これより前のバージョンの API ではこの要件は適用されません。

組織で生成された API 要求の数を監視するには、次の 2 つの方法があります。

• すべてのユーザが 24 時間以内に送信された API 要求の数を確認できます。情報を表示するには、[設定] から、[クイック検索] ボックスに「組織情報」と入力し、[組織情報] を選択します。右の列の [API 要求数 (この 24 時間以内)] を参照します。
• ユーザが「すべてのデータの編集」権限を持つ場合、7 日以内に送信された API 要求のレポートを参照できます。情報を参照するには、[レポート] タブで [管理レポート] セクションにスクロールして [過去 7 日間の API 使用状況] をクリックします。[集計情報:] ドロップダウンリストにある任意の項目でレポートを並び替えることができます。レポートの並び替え、絞り込み、カスタマイズの詳細は、Salesforce オンラインヘルプのレポートについての記述を参照してください。

最適なパフォーマンスを維持し、すべてのお客様が Lightning Platform API を使用できるようにするために、Salesforce は次の 2 つ種類の制限を設けることによって、トランザクションの負荷を調整しています。

• 同時 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 圧縮をサポートします。

ほとんどのクライアントでは、HTTP 1.1 の永続接続を使用し、複数の要求のソケット接続を再利用したほうがパフォーマンスが向上します。永続接続は通常 SOAP/WSDL クライアントが自動的に処理します。詳細は、次の HTTP 1.1 の仕様を参照してください。

http://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.1

HTTP 1.1 を使用しているクライアントは、チャンクレスポンスを受け取ることがあります。チャンクは通常 SOAP/WSDL クライアントが自動的に処理します。

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 の範囲外の文字は、切り捨てられるか、エラーとなります。

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 は各非文字列項目に Boolean 型の項目を生成します。たとえば、MyDateField__c に日付値がある場合、.NET は MyDateField__cSpecified と呼ばれる Boolean 型の項目を生成します。

生成される項目値は、デフォルトでは false です。指定された項目値が false である場合、対応する元の項目の値は SOAP メッセージには含まれません。たとえば、通貨項目 annualRevenue の値をクライアントアプリケーションが生成した SOAP メッセージに含める前に、annualRevenueSpecified の値を true に設定する必要があります。