実装に関する考慮事項

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

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

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

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

1http://login.salesforce.com/services/Soap/c/38.0

• http://login.salesforce.com/services/Soap/c/38.0 (Enterprise WSDL)
• http://login.salesforce.com/services/Soap/u/38.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 コール
• 記述用の API コール (describe)
• ユーティリティ API コール

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

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

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

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

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

Salesforce は数多くのデータベースサーバインスタンスを提供しています。通常組織は地理的な地域ごとに分けられていますが、組織はあらゆるインスタンスに置かれる可能性があります。

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

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

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

最適なパフォーマンスを維持し、すべてのお客様が Force.com 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

UTF-8 エンコードでは、Salesforce は基本的な UCS-2 エンコード (2 バイト、Basic Multilingual Plane) のみをサポートしており、拡張 UCS-4 文字はサポートしていません。UCS-4 のサポートは、どのシステムにおいても非常にまれです。UCS-2 は、Java や Windows がサポートしているエンコードです。XML 文字や文字セットの詳細は、http://www.w3.org/TR/REC-xml#charsets を参照してください。

.NET と Enterprise WSDL を共に使用した場合、.NET は各非文字列項目に追加の Boolean 型の項目を生成します。たとえば、MyField__c に日付値がある場合、.NET はそれぞれに Boolean 型の項目を生成します。この場合は、生成された項目は MyField__cSpecified と LastModifiedSpecified です。これらの項目値は、デフォルトでは false です。指定された項目値が false である場合、対応する元の項目の値は SOAP メッセージには含まれません。

たとえば、通貨項目 annualRevenue の値をクライアントアプリケーションが生成した SOAP メッセージに含める前に、annualRevenueSpecified の値を true に設定する必要があります。

1account.annualRevenue = 10000;
2account.annualRevenueSpecified = true;