SOAP API を使用する

学習の目的

この単元を完了すると、次のことができるようになります。

組織の WSDL ファイルを生成する。
SoapUI を使用して WSDL ファイルから SOAP プロジェクトを作成する。
SOAP API を使用して Trailhead Playground にログインする。
SOAP API を使用して取引先を作成する。

Enterprise WSDL と Partner WSDL

他の SOAP ベース API の海峡を航行したことがあれば、Web Services Description Language (WSDL) ファイルとは基本的に、API の使用方法を理解するための地図であることをご存知でしょう。このファイルには、API コールを行うためのバインド、プロトコル、オブジェクトが含まれています。

Salesforce では、ユースケースに応じて選択できる 2 つの SOAP API WSDL を提供しています。Enterprise WSDL は、単一の Salesforce 組織向けに最適化されています。強く型付けされていて、組織に固有の設定を反映しています。つまり、2 つの異なる組織から生成された Enterprise WSDL ファイルには異なる情報が含まれています。

Partner WSDL は、多数の Salesforce 組織で使用するために最適化されています。あまり強い型付けでなく、組織に固有の設定に基づいて変更されません。通常、単一の Salesforce 組織のインテグレーションを記述する場合は、Enterprise WSDL を使用します。複数組織の場合は、Partner WSDL を使用します。

この単元では、Enterprise WSDL を使用して SOAP API について説明します。最初のステップでは、組織の WSDL ファイルを生成します。Trailhead Playground で、[設定] から、[クイック検索] ボックスに「API」と入力し、[API] を選択します。API WSDL ページで、[Enterprise WSDL の作成] をクリックします。

[Enterprise WSDL の生成] ページで [生成] をクリックします。WSDL が生成されたら、ページを右クリックし、WSDL を XML ファイルとしてコンピューター上の任意の場所に保存します。これは後ほど使用します。

Enterprise WSDL を使用する場合に注意することがあります。Enterprise WSDL は組織に固有の設定を反映しています。そのため、組織のメタデータを変更するたびに、WSDL ファイルを再生成します。これにより、WSDL ファイルが組織の設定と同期が取れた状態が保たれます。

SoapUI を使用した SOAP プロジェクトの作成

WSDL ファイルができたところで、次は SOAP API 要求を開始するために情報を抽出する方法が必要です。Web 業界用語では、このプロセスを WSDL の消費と呼びます。不運な船乗りたちを乗せた船をクラーケンが消化してしまうように、Web Services Connector (WSC) などのツールが WSDL ファイルを消費します。その後、ツールはクラスを作成し、それによってユーザーは一般的なプログラミング言語を使用して SOAP API による要求を行うことができます。

この単元では、SoapUI というサードパーティのツールを使用して、Enterprise WSDL ファイルを消費します。SoapUI は、Web サービスをテストするための無料でオープンソースのアプリケーションです。使用を開始するには、SoapUI の Web サイトから SoapUI OpenSource をダウンロードしてインストールします。SoapUI コンポーネントのみをインストールします。

SoapUI でバンドルおよび使用される Java のバージョンが、組織のセキュリティポリシーと互換性があることを確認してください。SoapUI で使用されている Java のバージョンは、SoapUI 内から [Help (ヘルプ)] | [System Settings (システム設定)] を選択して確認できます。SoapUI バージョン 5.6.0 のダウンロード時にエラーが発生した場合は、Soap UI 5.5.0 などの以前のバージョンをダウンロードしてみてください。

SoapUI のインストールと起動が完了した後に、[File (ファイル)] メニューから [新規 SOAP プロジェクト] を選択します。プロジェクト名に「Exploring Salesforce SOAP API」 (Salesforce SOAP API の探索) と入力します。初期 WSDL に、Enterprise WSDL ファイルを保存した場所を参照してファイルを選択します。その他のオプションは変更しません。SoapUI ウィンドウは次のようになります。

SoapUI での「Exploring Salesforce SOAP API」 (Salesforce SOAP API の探索)

[OK] をクリックします。数秒間の処理の後、画面左側のナビゲーターパネルに Exploring Salesforce SOAP API フォルダーが表示されます。その下に SoapBinding というエントリがあり、いくつかの操作が含まれています。

これらは何でしょう? 各操作は、実行できる SOAP API 要求に対応しています。各操作のプロパティは、WSDL ファイルの情報から取得されています。各操作には、サンプルの XML 要求も含まれ、その中には操作の HTTPS エンドポイントと事前入力された SOAP メッセージが含まれています。

最後にもう 1 つ、Salesforce ではすべての接続で TLS 1.2 以降を使用する必要があります。Java 7 で SoapUI を使用している場合、TLS 1.2 はデフォルトでは無効です。古いバージョンの TLS で Salesforce に接続しようとすると、エラーメッセージが表示されます。幸いにも、この問題は簡単に修正できます。詳細は、この便利なブログ投稿を参照してください。

これで、SOAP API 要求を行う準備が整いました。では先に進みましょう。

Trailhead Playground にログインします。

SoapUI で、login 操作までスクロールダウンします。展開し、[要求 1] をダブルクリックします。サンプルの SOAP ログイン要求が表示されます。

エンドポイント URI (1) の各部分は次のとおりです。

https:// — セキュアな HTTP を指定します。
login.salesforce.com — ログイン要求の最上位ドメイン。
/services/Soap — SOAP API 要求を行うことを指定します。
/c — Enterprise WSDL を使用することを指定します。Partner WSDL の場合は /u を使用します。
/36.0 — API バージョン番号。v プレフィックスはありません。これは、API にはバージョン番号の前にプレフィックスが含まれているものとそうでないものがあるためです。このようになっているのは、Salesforce API のただの気まぐれです。
/0DF36000000LHZw — パッケージバージョン番号。

この例では管理パッケージを使用しません。そのため、URI の末尾からパッケージバージョンを削除できます。ここで、それを実行しましょう。

SOAP メッセージ (2) には、SOAP メッセージに本来含まれているエンベロープ、ヘッダー、ボディがすべて揃っています。

LoginScopeHeader 要素内のプロパティは、セルフサービスポータルおよびカスタマーポータルのユーザー認証に関するものです。ここでは、これらの値について考慮する必要がないため、<urn:LoginScopeHeader> 要素全体 (<urn: LoginScopeHeader> から </urn:LoginScopeHeader> までのすべて) を削除します。ウィンドウ内のテキストを強調表示して、Delete キーを押します。

次に、メッセージボディの <urn:login> 要素を見てみましょう。この要素は、ログイン要求の大部分です。ここでユーザーのログイン情報を指定します。? を Trailhead Playground のユーザー名とパスワードに置き換えます。

これを行うには、Trailhead Playground のログイン情報が必要です。アプリケーションランチャーで、[Playground Starter] を見つけて開き、以下の手順に従います。Playground Starter アプリケーションが表示されない場合は、Trailhead ヘルプの「Find the username and password for your Trailhead Playground (Trailhead Playground のユーザー名とパスワードの調べ方)」を参照してください。

[Get Your Login Credentials (ログイン情報の表示)] タブをクリックし、ユーザー名をメモします。
[パスワードのリセット] をクリックします。これにより、ユーザー名に関連付けられているアドレスにメールが送信されます。
メール内のリンクをクリックします。

Salesforce が認識しない IP アドレスから API 要求を行っているため、パスワードの末尾にセキュリティトークンを追加する必要があります。たとえば、パスワードが mypassword で、セキュリティトークンが XXXXXXXXXX である場合、<urn:password> 要素内に「mypasswordXXXXXXXXXX」と入力します。

セキュリティトークンを取得するには、個人設定に移動し、[私の個人情報] の [私のセキュリティトークンのリセット] ページに移動します。[セキュリティトークンのリセット] をクリックして、トークンを使用する Trailhead Playground に関連付けられているメールアドレスにメールを送信します。

SOAP メッセージは次のようになります。

要求ウィンドウの左上にある再生ボタン (緑色の三角形) をクリックします。このボタンをクリックすると、要求が送信され、SOAP メッセージは瓶に入れられて海に流されます。応答を展開すると次のようになります。

おめでとうございます、船長。ログインに成功しました。応答には、組織とユーザーに関するさまざまな情報が含まれています。最も重要なのは、組織の [私のドメイン] の名前 ([私のドメイン] を使用していない場合はインスタンス) とセッション ID (次の図で強調表示されている部分) が含まれていることです。これらは今後の要求に使用します。

インスタンスとセッション ID をテキストファイルにコピーします。これらは、この後すぐに使用します。

組織のインスタンスは変更される可能性があるため、インテグレーションを構築するときにインスタンスに参照をハードコード化しないでください。代わりに、組織の [私のドメイン] のログイン URL を使用します。[私のドメイン] で、Salesforce 組織に顧客固有のドメインを設定します。[私のドメイン] はインスタンス名の変更に悩まされることがなく、独自のブランドを強調し、組織をより安全にし、ログインページをパーソナライズするためにも使用できます。Winter '21 リリースより前に作成された組織については、場合によってはこの機能を有効にする必要があります。[私のドメイン] の設定方法については、「ユーザー認証」を参照してください。

Trailhead Playground で [私のドメイン] はすでにオン

どの Trailhead Playground でも [私のドメイン] はデフォルトでオンになっています。Trailhead Playground で [私のドメイン] をオンにしたり、設定を変更しようとしないでください。[私のドメイン] の設定を変更すると、Playground 組織からロックアウトされることがあります。

Trailhead Playground URL で強調表示された [私のドメイン] の名前

本番組織では、[私のドメイン] で組織に固有のサブドメインを作成できます。組織のログイン URL に Salesforce インスタンス (https://na17.lightning.force.com など) が含まれている場合に、[私のドメイン] をリリースすると、会社固有のログイン URL (https://mydomainname.my.salesforce.com) に置き換えられます。

組織でカスタムコンポーネントを作成する場合やシングルサインオン (SSO) を設定する場合は、[私のドメイン] が必要です。Winter ’21 以降の組織として作成されたすべての本番組織、Developer Edition 組織、トライアル組織には、デフォルトで [私のドメイン] が用意されています。[私のドメイン] を本番組織で有効にする方法については、Salesforce ヘルプの「私のドメイン」を参照してください。[私のドメイン] と Trailhead Playground についての詳細は、こちらのナレッジ記事を参照してください。

取引先の作成

REST API と同様に、SOAP API を使用して取引先を作成しましょう。画面左側のナビゲーションパネルで、create 操作を探します。展開し、[要求 1] をダブルクリックします。

レコードの作成はログインよりも複雑なため、create() SOAP メッセージにはより多くの要素が含まれています。ほとんどの要素は要求ヘッダーに含まれていて、その多くは省略可能です。簡略化するために、ほとんどのヘッダー情報を削除しますが、これらのヘッダーによって提供されるオプションはレコードを作成するときに使用できます。各ヘッダーの機能については、『SOAP API 開発者ガイド』の「SOAP ヘッダー」トピックを参照してください。

ただし、SessionHeader は削除しません。ここには、login() 応答から取得したセッション ID を格納します。その他のヘッダーを <urn:EmailHeader> から </urn:AssignmentRuleHeader> まで削除しましょう。メッセージは次のようになります。

テキストファイルにコピーしておいたセッション ID を <urn:sessionId> タグ内の ? を置き換えるように貼り付けます。

メッセージボディをさらにいくつか変更します。まず、取引先を作成することを指定します。<urn:sObjects> タグ内のテキストを <urn:sObjects xsi:type="urn1:Account" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> のように変更します。この変更では、XML インスタンススキーマ宣言を使用して正しいレコードタイプを指定します。

さらに、取引先の名前を指定します。sObjects 要素内に <Name>Sample SOAP Account</Name> を追加します。fieldsToNull 要素と Id 要素も削除します。これでメッセージは次のようになります。

要求を実行する前に、もう 1 つ行うことがあります。エンドポイントを login ではなく組織のインスタンスを指定するように変更し、URI の末尾からパッケージバージョンを削除します。エンドポイント URI は、https://MyDomainName.trailblaze.develop.my.salesforce.com/services/Soap/c/36.0 のようになります。

要求を送信する準備ができました。緑色の三角形を再びクリックします。うまくいきました! 応答を見てみましょう。

LimitInfoHeader を見てみましょう。このヘッダーは、API の使用状況に関する情報を返します。上の例では、今日実行できる 100,000 回のコールのうち、9 回を実行しています。

レスポンスボディの <result> 要素を見てみましょう。<success>true</success> は、レコードが正常に作成されたことを示しています。<id> にはレコードの ID が含まれ、この ID を今後の要求に使用できます。

SOAP API を使用した要求の実行の基本を説明しました。もちろん、各操作には、それぞれのパラメーターや特徴があります。SOAP API を使用してインテグレーションの記述を始めるときには、『SOAP API 開発者ガイド』を地図としてご利用ください。