SOAP API を使用する

学習の目的

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

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

メモ

日本語で受講されている方へ
Challenge は日本語の Trailhead Playground で開始し、かっこ内の翻訳を参照しながら進めていってください。Challenge での評価は英語データを対象に行われるため、英語の値のみをコピーして貼り付けるようにしてください。日本語の組織で Challenge が不合格だった場合は、(1) この手順に従って [Locale (地域)] を [United States (米国)] に切り替え、(2) [Language (言語)] を [English (英語)] に切り替えてから、(3) [Check Challenge (Challenge を確認)] ボタンをクリックしてみることをお勧めします。

翻訳版 Trailhead を活用する方法の詳細は、自分の言語の Trailhead バッジを参照してください。

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 で、[Setup (設定)] から、[Quick Find (クイック検索)] ボックスに「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 (システム設定)] を選択して確認できます。詳細は、www.soapui.org を参照してください。

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

[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 アプリケーションが表示されない場合は、Salesforce ヘルプの「Trailhead Playground のユーザー名とパスワードの調べ方」を参照してください。

1. [Get Your Login Credentials (ログイン情報を取得する)] タブをクリックし、ユーザー名をメモします。
   
2. [Reset My Password (パスワードのリセット)] をクリックします。ユーザー名に関連付けられているアドレスにメールが送信されます。
   
3. メールに記載されたリンクをクリックします。
   

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

画面右上のアバターをクリックし、[Settings (設定)] を選択してから、[My Personal Information (私の個人情報)] の下の [Reset My Security Token (私のセキュリティトークンのリセット)] を選択します。[Reset Security Token (セキュリティトークンのリセット)] をクリックして、トークンを使用する Trailhead Playground に関連付けられているメールアドレスにメールを送信します。

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

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

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

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

組織のインスタンスは変更される可能性があるため、インテグレーションを構築するときにインスタンスに参照をハードコード化しないでください。代わりに、組織の [私のドメイン] のログイン URL を使用します。[私のドメイン] で、Salesforce 組織に顧客固有のドメインを設定します。[私のドメイン] はインスタンス名の変更に悩まされることがなく、独自のブランドを強調し、組織をより安全にし、ログインページをパーソナライズするためにも使用できます。

取引先の作成

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 開発者ガイド』を地図としてご利用ください。

リソース

• SOAP API 開発者ガイド
• SOAP API Cheatsheet (SOAP API 早見表)
• SOAP API Sample WSDL Structures (SOAP API のサンプル WSDL の構造)
• SOAP API Web Services Connector (WSC)
• SoapUI ホームページ