目次


Salesforce.com オブジェクトを公開するための Web API を作成する

IBM WebSphere Cast Iron の Web API サービスを使用した簡易アセンブル

Comments

はじめに

Web API は、企業が新しい市場に参入し、新しい顧客やパートナーを獲得するのに役立つビジネス・チャネルとして急成長しており、社内の開発者によるイノベーションのみならず、大規模な開発者コミュニティーによるイノベーションを利用する上でも役立ちます。

Web API は、製品カタログや電話番号リストなどの主要なビジネス・アセットとサービスを公開することから、企業の顔という役割があります。したがって、Web API は自己記述的であり、使いやすくなければなりません。また、ブラウザーやモバイル機器から簡単に Web API を呼び出せるように、REST (Representational State Transfer) アーキテクチャー・スタイルが適用されている必要もあります。

IBM WebSphere Cast Iron の Web API サービスを使用すれば、わずか数回のクリックで API をアセンブルして公開することができます。さらに、提供されている分析機能を使用して Web API の使用状況を分析することも、ブランドの開発者ポータルでコミュニティー・フックを使用して Web API コミュニティーをソーシャル化することもできます。この記事では、WebSphere Cast Iron Web API サービスを使用して、Salesforce.com の CRM (顧客関係管理) システム内に連絡先を作成するために呼び出すことができる Web API の作成方法をステップバイステップで説明します。

前提条件

この記事の主な対象読者は API 開発者です。初心者でも手順を完了できるように、サンプル Web API を作成する際のステップを詳しく説明しますが、JSON (JavaScript Object Notation) および REST の予備知識があると、記事の内容をより深く理解することができます。

この記事のサンプル・アプリケーションを実装するには、以下のものが必要です。

  • 標準的なインターネット・ブラウザー (Google Chrome 18 以降、Mozilla Firefox 10 以降、または Internet Explorer 9 以降) がインストールされているワークステーション
  • インターネット接続
  • 有効な Cast Iron Web API 管理 ID とログイン資格情報 (無料の試用版にサインアップすることができます)
  • 有効な Salesforce.com アカウントとログイン資格情報 (開発者用アカウントにサインアップすることができます)

Web API の作成およびテスト

Salesforce.com を利用して CRM 情報を保管しているものの、その情報には社内の従業員しかアクセスすることができない企業があるとします。この企業では、Web API を公開し、Salesforce.com 環境にアクセスできる革新的なモバイル・アプリケーションをアプリケーション開発者たちが作成できるようにしたいと考えています。アプリケーション開発者が作成するアプリケーションとして考えられるのは、例えば顧客が販売担当員から連絡が欲しい場合には、自分の連絡先の詳細情報を Salesforce.com に直接追加することができるアプリケーションです。この機能を使用できるようにするには、この記事で順を追って説明する手順に従って、「create_contact」という名前のリソースを公開する Salesforce.com 用 Web API を作成してテストしてください。

  1. ブラウザーで https://webapi.castiron.com を開いて、Cast Iron Web API サービスを起動します。
  2. 右上にある「Sign In (サインイン)」をクリックし、表示されたウィンドウに資格情報を入力して、「Sign In (サインイン)」をクリックします (図 1 を参照)。
    図 1. Cast Iron Web API サービスにサインインする
    Cast Iron Web API サービスにサインインする方法を示す画像
    Cast Iron Web API サービスにサインインする方法を示す画像
  3. 「Getting Started with Web API (Cast Iron Web API 入門)」ページで、「Create (作成)」または一番上にある「APIs (API)」メニュー項目をクリックして、新規 API を作成します (図 2 を参照)。
    図 2. 新規 API を作成する
    新規 API を作成する方法を示す画像
    新規 API を作成する方法を示す画像
  4. 「Create new API (新規 API の作成)」ボックスで、API 名として「Salesforce.com」、コンテキストとして「Salesforce.com」、API の説明として「API to expose Salesforce.com objects (Salesforce.com 用オブジェクトを公開するための API)」と入力します (図 3図 4 を参照)。

    「Create new API (新規 API の作成)」ボックスの下部に、API の URI (Uniform Resource Indicator) が表示されることに注意してください。URI のフォーマットは以下のとおりです。

    https://<company>.web.castiron.com/<context>,

    ここで、<company> は作成する Web API の対象会社名、<context> はこのボックスで入力したコンテキストです。

    「Create (作成)」をクリックします。

    図 3. API 名と API の説明を入力する
    API 名と API の説明を入力する方法を示す画像
    API 名と API の説明を入力する方法を示す画像
    図 4. API のコンテキストを入力する
    API のコンテキストを入力する方法を示す画像
    API のコンテキストを入力する方法を示す画像

    作成された API が、「Create new API (新規 API の作成)」ボックスの下に表示されます。

  5. API を編集してリソースを追加するために、API 名をクリックします (図 5 を参照)。
    図 5. API 名をクリックして API を編集する
    API 名をクリックすることにより、API を編集する方法を示す画像
    API 名をクリックすることにより、API を編集する方法を示す画像

    あるいは、ウィンドウの右側にある鉛筆アイコンをクリックするという方法もあります (図 6 を参照)。

    図 6. 別の方法として、鉛筆アイコンをクリックして API を編集する
    鉛筆アイコンをクリックすることにより、API を編集する方法を示す画像
  6. 「Add a Resource (リソースの追加)」ボックスで、HTTP アクションとして POST を選択し、URI として「create_contact」、説明として「Create a Salesforce.com contact (Salesforce.com 内に連絡先を作成する)」と入力します (図 7 を参照)。
    図 7. リソースの詳細を入力する
    リソースの詳細を入力する方法を示す画像
    リソースの詳細を入力する方法を示す画像

    「Add a Resource (リソースの追加)」ボックスの下部に、リソースの URI が表示されます。URI のフォーマットは <API URI>/<resource URI> となります。ここで、<API URI> は上記で作成した API の URI、<resource URI> はこのボックスで入力した URI です。「Add (追加)」をクリックします。

    作成されたリソースは、「Add a Resource (リソースの追加)」ボックスの下に表示されます。

  7. リソースを編集して実装するために、リソース名をクリックします。
  8. リソース名をクリックすると表示される「Resource Details (リソースの詳細)」タブでは、そのリソースに関して、パラメーター、要求のヘッダー、要求の本文、応答のヘッダー、応答の本文を構成することができます。「Request Body (要求の本文)」テキスト域にリスト 1 の JSON コードを入力し、このリソースを呼び出すときに使用する要求の本文の構造を定義します。

    この例の API で設定できるのは、連絡先の名前、住所、e-メール・アドレスだけですが、ここに Salesforce.com 内の連絡先オブジェクトのすべてのフィールドを含めることもできます。リソースは、テキスト域の外側をクリックすると同時に自動保存されることに注意してください。

    リスト 1. JSON 形式での要求の本文の例
    {
        "FirstName": "Katherine",
        "LastName": "Sanders",
        "Street": "IBM Hursley",
        "City": "Winchester",
        "County": "Hampshire",
        "Postcode": "SO21 2JN",
        "Country": "UK",
        "Email": "katherine_sanders@uk.ibm.com"
    }
  9. 「Response Body (応答本文)」テキスト域には、リスト 2 に記載する JSON コードを入力して、このリソースが呼び出されると返される応答の本文の構造を定義します。

    Salesforce.com 内に連絡先が正常に作成されると、API はオブジェクト ID を返し、success の値が true に設定されます。一方、エラーが発生した場合は、success の値が false になり、ID の代わりにエラー・フィールドが設定されて返されることになります。

    リスト 2. JSON 形式での応答の本文の例
    {
        "id": "003A0000016nDhJIAU",
        "success": "true",
        "error_field": "",
        "error_message": "",
        "error_code": ""
    }
  10. 「Implement Resource (リソースの実装)」タブをクリックします (図 8 を参照)。

    このタブでは、構成の手法を利用してリソースの実装を定義します。データベース、Salesforce.com、およびその他の使用可能な API やサービスには HTTP でアクセスすることができます。

    図 8. リソースを実装する
    リソースの実装方法を示す画像
    リソースの実装方法を示す画像
  11. ウィンドウ左側の「Request (要求)」の下にあるプラス記号 (+) をクリックして、データ・ソースを追加します (図 9 を参照)。
    図 9. データ・ソースを追加する
    データ・ソースを追加する方法を示す画像
    データ・ソースを追加する方法を示す画像
  12. プラス記号 (+) をクリックすると表示されるメニューで、「salesforce.com」の下にある「Create objects (オブジェクトの作成)」を選択し、新規の要求アクティビティーを作成します。

    要求ごとに 1 つ以上の要求アクティビティーを作成することができます。

  13. 要求を構成するには、要求アクティビティーをクリックします (図 10 を参照)。
    図 10. 要求アクティビティーを構成する
    要求アクティビティーを構成する方法を示す画像
  14. 接続の名前と Salesforce.com の資格情報を入力した後、「Connect (接続)」をクリックします (図 11 を参照)。

    ウィンドウの下部に、接続が成功したかどうかを通知するステータス・メッセージが表示されます。また、入力した資格情報が、上部の「Existing Connections (既存の接続)」リストから選択できるようになるため、今後は資格情報を再入力する必要はありません。

    図 11. Salesforce.com に接続する
    Salesforce.com への接続方法を示す画像
    Salesforce.com への接続方法を示す画像

    Salesforce.com に正常に接続されると、構成の検出ステップが自動的にロードされます。Cast Iron Web API により、使用可能なオブジェクトのリストが Salesforce.com 環境からロードされます。

  15. 「Contact (連絡先)」オブジェクトを選択し、使用可能なフィールドのリストがページの右側にロードされるまで待ちます (図 12 を参照)。
    図 12. 連絡先オブジェクトを選択する
    連絡先オブジェクトの選択方法を示す画像
    連絡先オブジェクトの選択方法を示す画像
  16. 「Clear All (すべてクリア)」リンクをクリックしてチェック・ボックスのすべてをクリアしてから、要求の本文の値を設定するフィールドを選択します (図 13 を参照)。

    このサンプル・アプリケーションで必要となるフィールドは、FirstNameLastName (必須フィールドであるため、デフォルトで選択されます)、MailingStreetMailingCityMailingStateMailingPostalCodeMailingCountry、および Email です。これらのフィールドをすべて選択したら、ページの最上部にある「CONFIGURE (構成)」ステップをクリックします。

    図 13. 作成されるオブジェクトに設定するフィールドを選択する
    作成されるオブジェクトに設定するフィールドを選択する方法を示す画像
    作成されるオブジェクトに設定するフィールドを選択する方法を示す画像
  17. 新規連絡先オブジェクトで要求の本文のデータを Salesforce.com のフィールドにマッピングするには、2 つの方法のいずれかを使用することができます。「SELECT VALUES (値の選択)」をクリックして行う 1 つ目の方法では、「Select Available Value (使用可能な値の選択)」リンクをクリックすると、Salesforce.com の各フィールドと要求の本文で使用する値がロードされます (図 14 を参照)。

    右上にある「MAP VALUES (値のマップ)」をクリックすると、2 つ目の方法を利用することができます。

    図 14. 各フィールドの値を選択する
    各フィールドの値を選択する方法を示す画像
    各フィールドの値を選択する方法を示す画像
  18. 「Map Values (値のマップ)」をクリックして行う方法では、グラフィカルな方法で、要求の本文のフィールドを Salesforce.com のフィールドにマッピングすることができます。要求の各フィールドの隣にある丸を、対応する Salesforce.com のフィールド (表 1 に記載) までドラッグします (図 15 を参照)。

    オプションで、マッピングされた 2 つのフィールドの間にあるプラス記号をクリックして、そのマッピングに関数を適用することもできます。Cast Iron Express 製品ドキュメント (「参考文献」のリンクを参照) には、使用可能な関数をすべて網羅したリストがあります。

    図 15. 各フィールドの値をマッピングする
    各フィールドの値をマッピングする方法を示す画像
    各フィールドの値をマッピングする方法を示す画像
表 1. 要求のマッピング
要求の本文のフィールドSalesforce.com 内にある連絡先のフィールド
FirstNameFirstName
LastNameLastName
StreetMailingStreet
CityMailingCity
CountyMailingState
PostcodeMailingPostalCode
CountryMailingCountry
EmailEmail
  1. マッピングのテキスト・バージョンを表示するには、右上にある「SELECT VALUES (値の選択)」をクリックして最初のマッピング方法に戻ります (図 16 を参照)。

    左側に Salesforce.com のフィールドが一覧表示され、右側には要求の本文のフィールドが一覧表示されます。

    図 16. マッピングのテキスト・バージョンを表示する
    マッピングのテキスト・バージョンを表示する方法を示す画像
    マッピングのテキスト・バージョンを表示する方法を示す画像
  2. ページ左側の「Response (応答)」をクリックし、次に右側の「MAP VALUES (値のマップ)」をクリックします。リソースに関して、Salesforce.com の応答用フィールドから応答の本文のフィールドへのマッピング (表 2 に記載) を完了します (図 17 を参照)。

    success フィールドのマッピングが黄色で示されていることに注意してください。これは、データ型が一致していないためです。Salesforce.com のブール型 success フィールドは、自動的に応答の本文のストリング型 success フィールドに変換することが可能であるため、この警告は無視して構いません。マッピングの定義についての詳細は、「参考文献」を参照してください。

    図 17. 応答の本文のマッピング
    応答の本文のマッピングを示す画像
    応答の本文のマッピングを示す画像
表 2. 応答のマッピング
Salesforce.com の応答用フィールド応答の本文のフィールド
results/result/errors/fieldserror_field
results/result/errors/messageerror_message
results/result/errors/statusCodeerror_code
results/result/idid
results/result/successsuccess

これで、要求の本文で渡された情報を使用して Salesforce.com 内に連絡先を作成できるリソースの実装が完了しました。このリソースは、連絡先 ID または (連絡先を作成できなかった場合には) エラーの詳細のいずれかを含めた応答の本文を返します。実装は完了しましたが、リソースをテストするには、資格を作成する必要があります。

Web API ごとに、最大 3 つの API 資格レベルを定義することができます。これらの資格は、それぞれに異なる使用レベル、セキュリティー・レベル、料金設定レベルを反映します。ページの上部にある「Salesforce.com」リンクをクリックして API 構成に戻り、「Entitlements (資格)」タブをクリックしてください。「Add an Entitlement (資格の追加)」ボックスでは、以下の情報を入力します。

  1. 名前として、「Basic (基本)」と入力します。
  2. 説明として、「Basic entitlement (基本資格)」と入力します。
  3. セキュリティー・レベルとして、「Requires Id (ID を要求)」と入力します。
  4. 1 分あたりの呼び出し回数として「10」と入力します。

入力が完了したら、「Add (追加)」をクリックします (図 18 を参照)。

図 18. 資格の名前、説明、1 分あたりの呼び出し回数を入力する
資格の名前、説明、1 分あたりの呼び出し回数を入力する方法を示す画像
資格の名前、説明、1 分あたりの呼び出し回数を入力する方法を示す画像

作成された資格は、「Add an Entitlement (資格の追加)」ボックスの下に表示されます。リソースをテストするには、リソースをアクティブ化する必要もあります。それには、ページの上部で「Resource Definition (リソース定義)」タブをクリックし、「create_contacts」リソースの隣にある「Play (再生)」アイコンをクリックしてこのリソースを起動します。

リソースが正常にアクティブ化されたことを通知する情報ウィンドウが表示されます。このウィンドウで「OK」をクリックすれば、リソースをテストする準備は完了です。

テスト

作成したリソースをテストするには、以下の手順に従います。

  1. 「Test (テスト)」タブをクリックし、このタブの「Resource (リソース)」リストから「create_contact」リソースを選択します (図 19 を参照)。

    これにより、リソースの構成で使用したリスト 1 のサンプル要求の本文がロードされます。

    図 19. テスト対象のリソースを選択する
    テスト対象のリソースを選択する方法を示す画像
    テスト対象のリソースを選択する方法を示す画像
  2. 「Application (アプリケーション)」リストから「Test application (テスト・アプリケーション)」を選択し、「Test (テスト)」をクリックします (図 20 を参照)。

    このアプリケーションは、最初にアプリケーションを作成しなくてもリソースをテストできるように用意されています。

    図 20. テスト・アプリケーションを選択する
    テスト・アプリケーションを選択する方法を示す画像
    テスト・アプリケーションを選択する方法を示す画像
  3. 画面の下半分に応答が表示されるまで待ちます (図 21 を参照)。

    エラー関連のフィールドが 3 つとも空であること、success フィールドが true であること、id フィールドに Salesforce.com 内に作成された連絡先の ID が格納されていることから、リクエストが成功したことがわかります。

    図 21. 成功した場合の応答
    成功した場合の応答を示す画像

    今度は、応答のエラー関連のフィールドに正しく値が取り込まれることを確認するために、エラーが発生した場合をテストします。

  4. 要求の本文の LastName を空の値に変更し、「Test (テスト)」をクリックします。

    LastName フィールドは Salesforce.com で必須のフィールドであることから、期待通りに応答の本文ではエラーが返されます。つまり、連絡先を作成できなかったため、id は空となっています (図 22 を参照)。

    図 22. エラーが発生した場合の応答の本文
    エラーが発生した場合の応答の本文を示す画像
    エラーが発生した場合の応答の本文を示す画像

まとめ

この記事では、Cast Iron Web API を使用して Salesforce.com の Web API を作成する方法を実演し、API で「create_contact」という名前のリソースを公開する方法、そしてこのリソースに対して 2 つの HTTP POST リクエストを送信することにより、リソースをテストする方法を説明しました。テストの最初の要求では、Salesforce.com 内に連絡先が正常に作成されて ID が返されました。2 番目の要求は失敗し、ID の代わりにエラーの詳細が期待通りに返されました。

開発者コミュニティーに API をリリースする準備ができたら、API 構成ページの右上にある「Public (公開)」をクリックして、API を公開してください。こうすることで、開発者ポータルで API が表示されるようになります。開発者ポータルには、Web API のドキュメントで説明されている手順に従うことでアクセスすることができます。

また、企業のブランドに合わせて開発者ポータルをカスタマイズする必要があります。ポータルのページは重要です。なぜなら、外部ユーザーに表示されるこれらのページは、企業の宣伝となり、新しいビジネス機会を作り出す鍵となるためです。ページの構成にアクセスするには、ページの右上に示されている自分のユーザー名をクリックし、表示されるメニューで「Customize Developer Pages (開発者ページのカスタマイズ)」を選択します。詳細については、Web API のドキュメントを参照してください。

作成した Web API を開発者たちが使用するようになったら、それらのアプリケーション開発者たちや資格要求をモニターすることができるほか、API トラフィックを分析することもできます。


ダウンロード可能なリソース


関連トピック


コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Mobile development, Cloud computing, WebSphere
ArticleID=949521
ArticleTitle=Salesforce.com オブジェクトを公開するための Web API を作成する
publish-date=10242013