Salesforce1 Platform API サービスガイド
バージョン 2, 2014 年 9 月
このガイドには、すべての Salesforce API に関する包括的な情報が記載され
ています。このガイドを使用して、Salesforce API を使用する必要がある一
般的なシナリオを探索してください。ニーズに適した API が判明したら、こ
のガイドを使用して、詳しい API の概要、例、ベストプラクティスなどを取
得できます。
Salesforce1 Platform API サービスガイド
© Copyright 2000–2015 salesforce.com, inc. All rights reserved. Salesforce およびその他の名称や商
標は、salesforce.com, inc. の登録商標です。本ドキュメントに記載されたその他の商標
は、各社に所有権があります。
それぞれの商標は、それぞれの商標所有者に帰属します。
本出版物のいかなる部分も、発行者の事前の承諾なしに、電子的、機械的、写真複
写、録音、またはその他のいかなる手段を問わず、いかなる様式でも、複製、情報検
索システムへの保存、および伝達を禁止します。
目次
はじめに
....................................................3
第 1 章: Salesforce1 Platform の概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Salesforce1 の機能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
主要なビジネスの使用事例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Salesforce アプリケーションをカスタマイズしてモバイル対応にする . . . . . . . 8
的を絞ったマルチチャネルマーケティングキャンペーンを構築する . . . . . . . 10
顧客向けアプリケーションと従業員向けアプリケーションのインタラクショ
ンを作成する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
従業員がどこからでも会社データにアクセスできるようにする . . . . . . . . . . 14
接続デバイスのリアルタイムデータを分析する . . . . . . . . . . . . . . . . . . . . . . 16
従業員の生産性を促進するモバイルアプリケーションを作成する . . . . . . . . . 17
ID およびデータのセキュリティを境界を越えて展開する . . . . . . . . . . . . . . . 19
第 2 章: Force.com の概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
第 3 章: Heroku の概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Heroku の主要な機能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Heroku クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Heroku から Salesforce1 API をコンシュームする場合のベストプラクティス . . . . . 39
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
第 4 章: ExactTarget の概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
開発者にとっての顧客タッチポイント . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Force.com
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
第 5 章: 認証 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
接続アプリケーションの定義 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
OAuth エンドポイントについて . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Web サーバ OAuth 認証フローについて . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
目次
ユーザエージェント OAuth 認証フローについて . . . . . . . . . . . . . . . . . . . . . . . . . 62
ユーザ名パスワード OAuth 認証フローについて . . . . . . . . . . . . . . . . . . . . . . . . . 66
OAuth 更新トークンプロセスについて . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
その他のリソースを見つける . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
第 6 章: SOAP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
第 7 章: REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
前提条件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
ステップ 1: Salesforce Developer Edition 組織を取得する . . . . . . . . . . . . . . . . 254
ステップ 2: 認証を設定する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
ステップ 3: cURL で HTTP 要求を送信する . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
ステップ 4: サンプルコードを実行する . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
第 8 章: メタデータ API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
前提条件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
ステップ 1: 組織の Web サービス WSDL の生成または取得 . . . . . . . . . . . . . . 109
ステップ 2: 開発プラットフォームへの WSDL ファイルのインポート . . . . . . 110
ステップ 3: Java サンプルコードの説明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
第 9 章: Bulk API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Salesforce Developer Edition 組織の設定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
クライアントアプリケーションの設定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
cURL を使用した HTTP 要求の送信 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
ステップ 1: SOAP API を使用したログイン . . . . . . . . . . . . . . . . . . . . . . 138
ステップ 2: ジョブの作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
目次
ステップ 3: ジョブへのバッチの追加 . . . . . . . . . . . . . . . . . . . . . . . . . . 141
ステップ 4: ジョブの終了 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
ステップ 5: バッチの状況の確認 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
ステップ 6: バッチ結果の取得 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
データ読み込みに関する一般的なガイドライン . . . . . . . . . . . . . . . . . . . . . 146
レスポンスの圧縮の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
第 10 章: ストリーミング API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
ワークベンチを使用したクイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
前提条件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
ステップ 1: オブジェクトを作成する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
ステップ 2: PushTopic を作成する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
ステップ 3: PushTopic チャネルに登録する . . . . . . . . . . . . . . . . . . . . . . . . . 156
ステップ 4: PushTopic チャネルをテストする . . . . . . . . . . . . . . . . . . . . . . . 157
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
クライアントとタイムアウト . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
ストリーミング API のクライアントと Cookie . . . . . . . . . . . . . . . . . . . . . . . 159
サポートされるブラウザ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
HTTPS の推奨 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
ストリーミング API アプリケーションのデバッグ . . . . . . . . . . . . . . . . . . . . 160
イベント使用状況の監視 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
通知メッセージの順序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
第 11 章: Data.com API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Data.com 検索 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Data.com 照合 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Data.com 購入 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Data.com DUNSRight マッチング API: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Data.com ソーシャルプロファイルマッチング API . . . . . . . . . . . . . . . . . . . . . . . 168
Data.com レコードの購入 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
第 12 章: SOQL と SOSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
目次
第 13 章: Apex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Apex クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
最初の Apex コードおよびトリガの作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
カスタムオブジェクトの作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Apex クラスの追加 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Apex トリガの追加 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
テストクラスの追加 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
本番組織へのコンポーネントのリリース . . . . . . . . . . . . . . . . . . . . . . 183
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
クラウドでのコードの開発 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
テストの記述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
実行ガバナと制限について . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
第 14 章: Visualforce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
最初のページの作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Visualforce による項目値の表示 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Visualforce コンポーネントライブラリの使用 . . . . . . . . . . . . . . . . . . . . . . . 205
ページでの入力コンポーネントの使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
入力項目の表示ラベルの追加とカスタマイズ . . . . . . . . . . . . . . . . . . . . . . . 211
ページへの連動項目の追加 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Visualforce ダッシュボードコンポーネントの作成 . . . . . . . . . . . . . . . . . . . . 217
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Visualforce のパフォーマンス向上のためのベストプラクティス . . . . . . . . . 220
コンポーネント ID へのアクセスのベストプラクティス . . . . . . . . . . . . . . . 223
静的リソースのベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
コントローラおよびコントローラ拡張のためのベストプラクティス . . . . . . 231
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
第 15 章: Force.com Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
前提条件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
アプリケーションの作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
アプリケーションの場所の設定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
目次
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
第 16 章: Tooling API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
第 17 章: Salesforce1 レポート REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
コラボレーション
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
第 18 章: Chatter REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Chatter REST API クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
前提条件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
ステップ 1: Salesforce Developer Edition 組織を取得する . . . . . . . . . . . . . . . . 254
ステップ 2: 認証を設定する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
ステップ 3: OAuth を使用して Chatter REST API に接続する . . . . . . . . . . . . . . 256
Salesforce Communities への接続 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
モバイル . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
第 19 章: Salesforce Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
第 20 章: リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Marketing Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
第 21 章: ExactTarget API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Fuel を使用したメール送信 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Fuel SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
App Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
アプリケーションの作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
API の直接使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
目次
高度なパーソナライズ用のデータ拡張と AMPscript の使用 . . . . . . . . . . . . . . . . 292
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
第 22 章: Radian6 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
サポートされるブラウザ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
サポート対象の Salesforce のエディション . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
ステップ 1: API で認証する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
ステップ 2: メソッドへのコールを発行する . . . . . . . . . . . . . . . . . . . . . . . 309
ステップ 3: データを取得する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
サービスの使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Post サービス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Post サービスのリソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
User サービス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
User サービスのリソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Insight サービス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Insight サービスのリソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Topic サービス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Topic サービスのリソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Data サービス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Data サービスのリソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Blog サービス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Blog サービスのリソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Authentication サービス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Lookup サービス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Lookup サービスのリソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
第 23 章: Pardot API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
サポートされるブラウザ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
サポート対象の Salesforce のエディション . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
ステップ 1: API で認証する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
ステップ 2: Pardot API を使用して要求を発行する . . . . . . . . . . . . . . . . . . . 360
API の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
目次
prospect の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
opportunity の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
visitor の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
visitorActivity の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
user の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
visit の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
list の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
prospectAccount の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
メールの読み取り . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
1 対 1 メールの送信 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
リストメールの送信 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Service Cloud
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
第 24 章: Desk.com API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
サポートされるブラウザ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
サポート対象の Salesforce のエディション . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
ステップ 1: API で認証する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
ステップ 2: データを要求する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
API の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
記事用のコール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
brands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
ケース用のコール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
companies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
会社用のコール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Custom Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
顧客用のコール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
ETags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Facebook accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
目次
Facebook フィード . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Facebook ユーザ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
グループ用のコール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
inbound mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
insights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
integration URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
インテグレーション URL 用のコール . . . . . . . . . . . . . . . . . . . . . . . . . 427
jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
表示ラベル用のコール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
マクロ用のコール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Outbound Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
site settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
system message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
トピック用のコール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Twitter accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Twitter アカウント用のコール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
Twitter ユーザ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
ユーザ用のコール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
第 25 章: Live Agent API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
サポート対象の Salesforce のエディション . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
前提条件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
API バージョン . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
リリースの作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
リリース API を使用してリリースをカスタマイズする . . . . . . . . . . . . . . . . . . . 450
リリースの作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
リリース API を使用したリリースアクティビティのログ記録 . . . . . . . . . . . 451
目次
enableLogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
リリース API を使用したチャットウィンドウのカスタマイズ . . . . . . . . . . . 452
setChatWindowHeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
setChatWindowWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
リリース API を使用したチャット要求の起動 . . . . . . . . . . . . . . . . . . . . . . . 454
startChat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
startChatWithWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
リリース API を使用した訪問者の詳細のカスタマイズ . . . . . . . . . . . . . . . . 456
addCustomDetail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
setName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
リリース API を使用したレコードの自動作成 . . . . . . . . . . . . . . . . . . . . . . . 460
findOrCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
レコード作成のリリース API のコードサンプル . . . . . . . . . . . . . . . . . 465
リリース API を使用したチャットボタンのカスタマイズ . . . . . . . . . . . . . . 466
showWhenOnline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
showWhenOffline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
addButtonEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
リリース API を使用した自動チャット招待のカスタマイズ . . . . . . . . . . . . . 471
rejectChat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
addButtonEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
setCustomVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
自動チャット招待のコードサンプル . . . . . . . . . . . . . . . . . . . . . . . . . 474
開発 API のコードサンプル . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
事前チャット API を使用したチャットの詳細へのアクセス . . . . . . . . . . . . . . . . 481
preChatInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
事前チャット API を使用してレコードを自動作成する . . . . . . . . . . . . . . . . . . . 484
findOrCreate.map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
findOrCreate.map.doFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
findOrCreate.map.isExactMatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
findOrCreate.map.doCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
findOrCreate.saveToTranscript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
findOrCreate.showOnCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
findOrCreate.linkToEntity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
findOrCreate.displayToAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
レコード作成の事前チャット API のコードサンプル . . . . . . . . . . . . . . . . . . 494
目次
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
第 26 章: Salesforce コンソールインテグレーションツールキット . . . . . . . 497
サポートされるブラウザ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
サポート対象の Salesforce のエディション . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
ツールキットへの接続 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Salesforce コンソールインテグレーションツールキットを使用した非同期
コール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Force.com Canvas の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Salesforce コンソールインテグレーションツールキットを使用したサンプル
Visualforce ページ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
メソッド . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
主タブとサブタブ用のメソッド . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
コンピュータテレフォニーインテグレーション (CTI) のメソッド . . . . . . . . . 514
アプリケーションレベルのカスタムコンソールコンポーネント用のメソッ
ド . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
転送通知用のメソッド . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Live Agent のメソッド . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
第 27 章: Open CTI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
サポートされるブラウザ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
サポート対象の Salesforce のエディション . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
クイックスタート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
Open CTI への接続 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Open CTI での非同期コール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Force.com Canvas の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
ベストプラクティス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
コールセンター定義ファイル . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
コールセンター定義ファイルの XML 形式 . . . . . . . . . . . . . . . . . . . . . . . . . 533
コールセンターの必須要素と必須属性 . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
コールセンターの省略可能な要素と属性 . . . . . . . . . . . . . . . . . . . . . . . . . . 537
コールセンター定義ファイルのサンプル . . . . . . . . . . . . . . . . . . . . . . . . . . 538
目次
メソッド . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Salesforce アプリケーション操作用のメソッド . . . . . . . . . . . .
コンピュータテレフォニーインテグレーション (CTI) のメソッド
リソース . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
539
540
542
543
本書について
本書では、Salesforce1 Platform のすべての API の包括的なツアーを提供します。次のよう
な構成になっています。
• はじめに — Salesforce1 Platform とその主要コンポーネント (Force.com、Heroku、およ
び ExactTarget Fuel) の概要
• Force.com — Force.com の API と開発ツール
• コラボレーション — Chatter REST API
• モバイル — Mobile SDK (HTML5、iOS、および Android のすべての開発者ツールを含む)
• Marketing Cloud — ExactTarget、Radian6、および Pardot の API
• Service Cloud — Desk.com、Live Agent、Open CTI、コンソールインテグレーションツー
ルキットの API
本書を読めば、Salesforce1 Platform の機能を的確に理解できます。開発を開始する準備
ができたら、各 API のドキュメントを参照して、技術的な詳細やリファレンス情報を
確認してください。
1
はじめに
第1章
Salesforce1 Platform の概要
モバイルは、プライベートでも仕事でもインターネットに接続する標準的なツールに
なりました。友達をフォローする、状況フィードを更新する、ローカルビジネスを調
査する、同僚とコラボレーションする、納入業者にメールを送信するなどの操作を外
出先で行うことが増えています。将来のビジネスを成功させるには、今日のモバイル
ファースト環境に適応する必要があります。モバイルがもたらす自由を活用すれば、
どこで何をしているかに関係なく作業を完了することが可能になります。
企業のコンシューマモバイルアプリケーションは、機能性や導入の面でデスクトップ
アプリケーションに遅れをとっています。多くの IT 部門では社内にモバイルのエキス
パートが存在しません。また、現在進行中のプロジェクトからの要求に応えるために
貴重な技術者を割り当てる必要があります。カスタムモバイルアプリケーションを提
供している場合、開発サイクルが長く複雑で費用がかかるために、今日のコンシュー
マ向けの主要なアプリケーションのようにユーザとの関係を効率的に構築することが
できませんでした。
Salesforce1は、ソーシャルファーストとモバイルファーストの環境を対象にしたアプリ
ケーション開発に画期的な方法をもたらすことによって、モバイルの専門家不足や革
新の鈍化といった問題を解決します。顧客 (従業員、パートナー、コンシューマ、デ
バイス) をすべての中心に置き、すべての従業員をモバイル開発者にすることで、画
期的な生産性が全ユーザに提供されます。この結果、サービスとしてのソフトウェア
(Software as a Service) と同じくらい強烈な可能性を持つ超高速接続のモバイルソリュー
ションが生まれました。Salesforce1 で未来を構築しましょう。
Salesforce1 Platform では、自由な革新が組織に提供されます。拡張を念頭に置いて設計
されたこのプラットフォームは、強力な開発者ツールだけでなく、拡張や統合のため
のオープン API を提供します。開発者が構築できるものは無限です。Salesforce1 Platform
の柔軟な開発モデルを使用することで、すべてのシステム管理者または開発者が、独
自でありながら使い慣れたモバイルユーザの操作性とモバイルバックエンドサービス
を備えたカスタムアプリケーションを作成できます。
3
第 1 章 Salesforce1 Platform の概要
Salesforce1 の機能
Salesforce1 Platformは、幅広いユーザを対象にしたモバイルアプリケーション開発プラッ
トフォームです。このプラットフォームでは、ISV、開発者、システム管理者、そして
すべてのユーザが極めて自在にイノベーションに取り組めます。組織のモバイルアプ
リケーション開発を飛躍させるこの画期的なアプローチは、モバイルソリューション
やソーシャルソリューションを数週間あるいは数日のうちに提供するという今日の
ニーズに応えるために考案されたものです。メタデータ駆動のアプリケーションで
は、ユーザの操作に対してコンテキストがインテリジェントに提供され、情報ベース
のモバイルデバイス機能が実現されます。たとえば、応答性のある設計、地図上に配
置される住所項目、1 回のタップでダイヤルされる電話番号、フィード中心のワーク
フローなどです。
ビジネスユーザやシステム管理者は、コードなしのクリック操作でアプリケーション
を開発して、高性能のワークフロールール、承認プロセス、データベース、動的な
ユーザインターフェースを完備できます。他のソリューションではビジネスユーザが
独自のアプリケーションを作成し、IT 部門が可視性やセキュリティにほとんど関与で
きないことがよくありますが、Salesforce1では、革新に向けたビジネスの能力を制限す
ることなく、アプリケーションを一元的に管理および制御するために必要なツールが
システム管理者に提供されます。
大規模な拡張性、拡張や統合のためのオープン API、強力な開発者ツールにより、開
発者や ISV がこのプラットフォームで構築できるものに無限の可能性が与えられます。
Salesforce1の柔軟な開発モデルを使用することで、すべてのユーザが、モバイルバック
エンドサービスと独自でありながら使い慣れたモバイルユーザの操作性を備えたカス
タムアプリケーションを作成できます。Salesforce1 Platformで開発をする ISV は、Salesforce1
Platform 内のパッケージ化されたバージョン管理の高度な制御機能、AppExchange を含
む優れたエンタープライズクラスのマーケットプレイス機能、アプリケーションの
フィードファースト検出を活用するアプリケーションを開発できます。
Salesforce1 Platform は、Force.com、Heroku、ExactTarget Fuel が結集され、1 つの極めて強力
なソーシャル、モバイル、そしてクラウドサービスの体系を構成しています。これら
のサービスはすべて API ファーストで構築されています。Salesforce1 は、次の機能を備
えています。
4
第 1 章 Salesforce1 Platform の概要
ソーシャルデータ
このプラットフォームの中核をなすのが、Salesforce1 アプリケーション内で共有した
り、フォローしたり、コラボレーションしたり、データに対してビジネスアクション
を直接実行したりできる機能です。ユーザは 1 回のタップでレコードやデータをフォ
ローできます。リアルタイムで変更の通知を受信することや、レコードフィード内で
直接コラボレーションすることもできます。作業に対してこのフィードベースアプ
ローチを使用することで、ユーザは最も重要な点に焦点を絞ることができます。
Salesforce1では、データをソーシャルツールと位置づけ、ビジネスに積極的に関与させ
ることで、データによってワークフローをトリガしたり、更新を共有したりするほ
か、作業者やチーム、パートナーや顧客とのコラボレーションプロセスの一環として
データを活用します。その結果、ビジネスの生産性を高める新しいビジネスアプリ
ケーションやプロセスを作成する、かつてない機会が生まれます。
宣言型およびプログラム型の開発
IT 部門は、競争上の優位性を保つために、ビジネスに求められる変化のペースに遅れ
を取らないよう必死に取り組んでいます。IT 部門は、既存の社内システムを管理しな
がら、特にモバイルアプリケーションの開発経験のある専門的な開発者を採用してつ
なぎ留めておく必要があるため、リソース面で制約されることがよくあります。
Salesforce1では、データの保存や操作、ワークフローでのクラウドベースのロジックの
定義、承認プロセスや数式の作成、モバイル対応アプリケーションの作成を直観的な
ドラッグ & ドロップツールで行えるようにすることで、サービスの提供開始までに時
間がかかるという問題を解決します。
専門開発者は、ごく一般的なオープンソースの言語やツール、標準を使用して、完全
カスタム仕様のアプリケーションやユーザインターフェースを構築できます。Salesforce1
は、他のプラットフォームとは異なり、開発者とシステム管理者が同じプラットフォー
ム上でアプリケーションを作成するユニークな環境となるため、複雑なインテグレー
ションソリューションを構築する手間が省けます。
アクションベースのアプリケーションモデル
Salesforce1の開発プロセスの中心にあるのは顧客です。複雑な開発サイクルを要さず、
注文の作成、納品日の設定、経路の選択などのアクションを介してアプリケーション
を宣言できます。システム管理者は、アクションのデフォルト値を定義してアプリ
5
第 1 章 Salesforce1 Platform の概要
ケーションをスリム化し、マウスのクリックや指でのスワイプで操作できるようにし
ます。
デスクトップ経由で定義したアクションは、モバイルデバイス上の状況に応じたメ
ニューにすぐに反映されます。さらに、開発者が Salesforce1 とのインテグレーション
を構築する場合、XML または JSON データエンベロープを受け入れることができる RESTful
エンドポイントでアクションが自動的に有効になります。
オープン API ですべてに接続
Salesforce は接続性および柔軟性が高く、1 日に 13 億件を超えるトランザクションを実
行する効率的でスケーラブルな API を使用して、あらゆるものに接続するアプリケー
ションを作成できます。オブジェクトやデータエンティティがすぐに REST に対応しま
す。
salesforce.com の API では、データを読み込むバルク API、どこでも自在にコラボレーショ
ンするソーシャル API、転送通知のインテグレーションをサポートする最先端のスト
リーミング API、権限やデータアクセスポリシー、項目種別、ユーザの操作性など、
アプリケーションやビジネスのあらゆる面を記述するメタデータ API にアクセスでき
ます。
現在までのところ、開発者はプラットフォームで 500,000 以上のアプリケーションを作
成しています。これらのアプリケーションは、既存のバックエンドシステム、Google、
Facebook、Twitter などのクラウドプラットフォームや、冷蔵庫、車、自動販売機などの
増え続けている多くのコンシューマデバイスに接続しています。
信頼できる ID
今日の IT 環境は、社内システム、内部プロセス、クラウドプロバイダ、ソーシャル
ネットワーク、モバイルデバイスで構成されています。このような技術的にも業務的
にも分断された各種システムに 1 つの単純な ID で対応する機能は、ビジネスの成功や
変化の高速化を根底から支える要素です。ログイン数が年間 70 億を超える Salesforce1
では、境界ベースの ID 管理ソリューションを超えて到達し、プラットフォームのソー
シャルデータとマルチテナントコアを活用する、信頼できる ID ハブを提供します。
組織では、次のような標準を活用するソリューションを作成できます。
• 社内システムを使用して認証する SAML および代理認証
6
第 1 章 Salesforce1 Platform の概要
• ソーシャルプラットフォームおよびクラウドプラットフォームに接続するための
OAuth
• アプリケーションプロバイダが、信頼できる ID プロバイダとして Salesforce に接続
するための接続アプリケーションポリシー
さらに、Salesforce1では、場所に関係なく組織の異なる部署や異種システムにまたがっ
てレコード表示を制御する、使いやすい一元化されたポリシー管理ツールをサポート
しています。
主要なビジネスの使用事例
Salesforce1 Platform は、各アプリケーションをサポートし、顧客に利点もたらすように
設計されています。このプラットフォームは API ファーストおよびモバイルファース
トで、事業部門で操作するユーザも、IT を管理するユーザも、会社全体や商品全体の
構築を目指しているユーザも、あらゆる要素を拡張およびカスタマイズできます。ま
た、すべてのアプリケーションをすぐにモバイル対応にすることができます。
エンジニアリングの視点から、Salesforce1 には次のような指針があります。
• すべての新機能はモバイルファーストで設計され、開発者用のAPIが設定されてい
る必要があります。
• ユーザインターフェースは高い応答性を備え、アプリケーションの実行媒体 (ス
マートフォン、タブレット、またはラップトップ) に応じて動的に変化する必要が
あります。
• ユーザの操作性はデバイスの機能に応じて変化する必要があります。住所項目で
は、地理的位置を活用して、地図、近隣情報、およびコンテキストを表示する必
要があります。電話番号をクリックして電話をかけることができる必要がありま
す。
• アプリケーションはパーソナライズされている必要があります。ユーザインター
フェースは ID によって決まる必要があります。これは、カレンダー、個人設定、
および使用状況履歴と連携することで実現します。
• プラットフォーム全体がニーズに応じて進展し、常に顧客が各アプリケーション
および各アクションで利点を得られるようにする必要があります。
Salesforce1 は新たに再開発されたものではなく、変革されたものです。Salesforce では、
ユーザからの要望 (拡張、信頼性、ソフトウェアやハードウェアの排除、負担のない
アップグレード) に確実に対応するために何年もの間労力を注ぎ込んできました。
7
第 1 章 Salesforce1 Platform の概要
Salesforce で作成されたデータ、アプリケーション、カスタムロジック、ユーザイン
ターフェースを所有する既存のお客様は、この投資をすぐにモバイルに対応させるこ
とができます。将来を先取りする企業が明日のトップ企業になります。モバイルアプ
リケーションの構築に数か月または数年もかけるべきではありません。Salesforce1 に
よって、このモバイルファーストの未来を今すぐ手に入れることができます。
Salesforce1 は、ビジネスの成功へのカギとなります。Salesforce1 Platform での開発目的
は、顧客が利点を得られるアプリケーションを提供することです。このガイドのビジ
ネスの使用事例では、従業員、顧客およびパートナーが満足するアプリケーションを
提供するために要求される最も一般的なシナリオについて説明します。各シナリオで
は、目的とする顧客の利点、アプリケーションアーキテクチャの概要、および成功の
ために推奨される API と設計戦略などを示します。皆様は、「このアプリケーション
を使用すると顧客やエンドユーザにどのような利点があるか? また、どのように構築
するか?」という疑問を念頭に置いてこのセクションをお読みください。
Salesforce アプリケーションをカスタマイズしてモバ
イル対応にする
動機
現在の Salesforce ユーザの多くは、Salesforce で開発された既存のアプリケーションやプ
ロセスを持っています。Salesforce1を使用すれば、このすべての情報にすぐにアクセス
できるため、開発する必要がありません。
戦略
通常、Salesforce アプリケーションの開発は 2 つのカテゴリ (従来の Salesforce Web イン
ターフェースを使用する宣言型ツールで作成するカテゴリと、カスタムユーザイン
ターフェースやプログラムテクノロジ (Apex や Visualforce など) で作成するカテゴリ) に
分かれます。Salesforce1では、両方のタイプのアプリケーションをモバイルデバイスで
表示できます。ただし、ユーザインターフェースのカスタマイズのレベルによって
は、開発者は最適なユーザ環境を得られるように Visualforce および Apex ページを変更
する必要があります。負荷の高いデータ操作やグラフィックの多いアクティビティに
対応するように設計された複雑な Visualforce ページには特に注意を払う必要がありま
8
第 1 章 Salesforce1 Platform の概要
す。モバイル Web ページを開発する場合、ユーザが小型画面で直感的に操作できるよ
うにデータトラフィックやユーザインターフェースを最適化する必要があります。
開発開始
まず、カスタムアプリケーション、Visualforceページ、および完了までに複数のステッ
プ/ページを要するビジネスプロセスの一覧表を作成します。使用頻度に基づいて、
最適化の候補に順位をつけます。カスタムアクションを作成してステップを削減でき
るものがあれば、そうした候補を優先します。
次に、大幅な再コーディングをせずにパフォーマンスを最適化できる箇所を探しま
す。現在のブラウザ (Safari、Firefox、Chrome など) には、開発者がページの HTTP 要求の
相対的サイズや期間を確認できるツールが含まれています。すぐに変更できる候補の
例として、大きな画像ファイルのサイズを縮小する、サーバ側のビューステートを使
用するようにページを変更する、最適化されていない JavaScript ライブラリを圧縮 (-min
で終わる JavaScript ライブラリは圧縮されています) する、などが挙げられます。
9
第 1 章 Salesforce1 Platform の概要
的を絞ったマルチチャネルマーケティングキャンペー
ンを構築する
動機
顧客は、あらゆる種類のメッセージ (受信箱のメール、郵便受けの郵便物、高速道路
の広告板、モバイルデバイスの SMS や転送メッセージなど) を大量に受け取っていま
す。対象者の注意を引く、的を絞った関連性の高いマーケティングキャンペーンでな
ければ効果はありません。的を絞った関連性の高いコミュニケーションを行うこと
は、マーケティング担当者にとっての課題であると同時に、技術的な問題でもありま
す。マーケティングキャンペーンを大きく成功させるには、複数のデータソースから
のデータを、厳密に分類した対象者に結び付け、複数のチャネルで洗練されたインタ
ラクションを行うことが必要です。適切なメッセージを、適切な瞬間に提供する必要
があります。
戦略
顧客は、数十のソース (Web、モバイル、ソーシャルネットワークなど) を介して企業
とインタラクトします。対象となる顧客を効果的に絞り込むには、数か月かかる複雑
な IT プロジェクトを立ち上げることなく、柔軟なデータモデルおよびインテグレー
ション戦略を使用してシステム間でデータを同期できることが不可欠です。最悪なの
は、長期にわたる複雑なプロジェクトで実装を急ぎ、重要な顧客タッチポイントを失
うことです。
キャンペーンを成功させるには、対象を絞り、その対象にとって有意義なメッセージ
を伝えることが必要です。どれだけ対象者に関連性の高いメッセージを作れるかは、
顧客タッチポイントから得られる情報を分析する能力にかかっています。この顧客情
報を分析することで、マーケティング担当者は適切なメッセージを適切なタイミング
で提供できます。
10
第 1 章 Salesforce1 Platform の概要
開発開始
通常、開発者は ExactTarget Fuel を使用して、統合されたキャンペーンを構築します。
ExactTarget Fuel では、顧客タッチポイントをインテグレーションとして公開するための
開発者向け SDK が提供されます。顧客タッチポイントの設定は App Center 経由で行い
ます。Force.com の接続アプリケーションモデルに精通している開発者であれば、
ExactTarget App Center もほぼ同じであることに気付くと思います。App Center ポータルで
アプリケーションを作成して登録すれば、そのアプリケーションから Fuel プラット
フォームにアクセスして、ExactTarget の機能を活用できます。
11
第 1 章 Salesforce1 Platform の概要
顧客向けアプリケーションと従業員向けアプリケー
ションのインタラクションを作成する
動機
顧客は、ソーシャルネットワーク、Web サイト、およびモバイルアプリケーションを
介して製品やブランドと関わりを持ちます。ただし、多くの組織では、顧客向けアプ
リケーションと従業員向けアプリケーションのシステムが接続されていません。最良
の状態にするには、インテグレーションプロセスが複雑なものになるため、結果とし
て、多くの場合顧客の操作性が低くなっています。
戦略
Salesforce1では、プラットフォームのすべての要素を簡単に統合できるため、組織が顧
客の全体像を把握できます。Heroku は、コンシューマの拡張に対応し、現在最も一般
的なアプリケーションや Web サイトで使用されている最新の開発言語をサポートする
よう設計されています。Force.comは、従業員向けアプリケーション用に設計されてお
り、ビジネスデータを操作します。ExactTarget では、対象を絞ったメッセージおよび
マーケティングキャンペーンをユーザに送信できます。顧客とのシームレスなインタ
ラクションにより、これらの製品のすべての要素を活用できます。Salesforce1 Platform
では、開発者、ビジネスユーザ、および顧客に最適化された環境でこの機能を提供で
きます。
12
第 1 章 Salesforce1 Platform の概要
顧客向けアプリケーションを構築している開発者は、Heroku でアプリケーションを開
発して Heroku Connect を設定するか、言語固有のオープンソースライブラリを使用し
て API レベルのインテグレーションを行う必要があります。通常、インテグレーショ
ンでは、取引先責任者レコードとして顧客の詳細を管理する Force.com で確立されたイ
ンテグレーションユーザアカウントが使用され、コンシューマプロファイルとForce.com
アカウントが 1 対 1 で対応付けられることはありません。この分離したアプローチに
より、コンシューマ向けアプリケーションと従業員向けアプリケーションを個別に拡
張できます。
インテグレーションユーザと顧客コンタクト戦略が確立されたら、開発者とビジネス
ユーザは Heroku とForce.com間で同期する情報を特定する必要があります。顧客とビジ
ネス間のリレーションが形成されると、製品が適切なデータおよび同期のトリガを決
定する要因になります。たとえば、一般的な Web およびモバイルコンシューマアプリ
ケーションの場合、ユーザが特定の製品やサービスに登録するか、興味を示すまでは
一般的な情報が表示されます。こうしたリレーションが確立されるとすぐに、顧客企
業は、ユーザがどのようなことに興味があるのか、どのようにすれば対象を絞った
13
第 1 章 Salesforce1 Platform の概要
マーケティングメッセージを送付し、サービスチケットやソーシャルネットワークイ
ンタラクションなどの顧客コンタクトを追跡できるか、どのようなトレンド分析に
よってビジネスの優先度を適切に決定できるかなど、各ユーザに関する顧客プロファ
イルの構築を開始します。
開発開始
まず、顧客の操作性から対応します。システム間で同期するデータとその間隔を決定
するために使用するリレーションタッチポイントのリストを作成します。リストを作
成したら、開発チームは、各リレーションの維持や強化を行うための適切なテクノロ
ジ、拡張、フィードバックループを使用して、顧客向けおよび従業員向けのアプリ
ケーションを個別に開発できます。通常、Heroku アプリケーションはコンシューマ拡
張のステートレス利用モデルで設計され、Force.comアプリケーションはユーザに基づ
いて設計されます。タッチポイントとアプリケーションを作成したら、ビジネスユー
ザは顧客情報に基づいてレポートを作成する必要があります。これらのレポートか
ら、マーケティング担当者は ExactTarget を使用して、対象を絞ったキャンペーンを簡
単に作成できます。
従業員がどこからでも会社データにアクセスできるよ
うにする
動機
大半の組織は、既存のバックエンドシステムおよびカスタムアプリケーションに多大
な投資をしています。多くの場合、これらのシステムは現存する機能を適切に実行し
ますが、こうしたシステムを使用して新しいアプリケーション (特にモバイルアプリ
ケーション) を作成することは難しくコストがかかります。Salesforce1 には、既存のシ
ステムと顧客アプリケーションを結び付けるオープンな API があり、顧客がイノベー
ションを実現するための迅速なレイヤを作成できます。
戦略
既存のシステムは、企業ファイアウォールの内側、またはクラウドプロバイダ内にあ
ります。ETL (抽出、加工、読み込み) といったインテグレーションの従来のアプローチ
では、データアクセスの問題は解決できますが、重複データのサイロが構築されてし
14
第 1 章 Salesforce1 Platform の概要
まう可能性があります。可能であれば、「記録のためのシステム」(多くの場合、新し
いアプリケーション開発には使用されなくなった既存システム) を特定し、インテグ
レーション要件に基づいて、最も効率的な Salesforce1 API で Salesforce に接続します。た
とえば、演算のオーバーヘッドが高く、試行-再試行ロジックが複雑なポーリングベー
スのソリューションを避け、代わりにストリーミング API を使用します。
可能であれば、データ入力ソース (通常は、新しいアプリケーション開発用のSalesforce1)
のユーザ ID をターゲット (記録のためのシステム) に保持します。新しいアプリケー
ションイノベーションのソースとして Salesforce1 を使用して、システム間のデータの
整合性を確保する外部識別子を作成します。Salesforce1のアクションから実行でき、モ
バイルアプリケーションで使用できる既存のシステムのビジネスプロセスアクション
を公開します。このガイドの「ID およびデータのセキュリティを境界を越えて展開す
る」セクションで定義されている ID 管理の戦略を活用します。
開発開始
まず、データアクセスだけのニーズではなく、ビジネスニーズから開始します。ビジ
ネスニーズを明確にすれば、「記録のためのシステム」ベースのアプローチが適切な
のか、Salesforce1 のどの API が最適なのかを判断できます。たとえば、データの読み込
みには Bulk API、パブ/サブモデルにはストリーミング API、タップで開始できシステム
15
第 1 章 Salesforce1 Platform の概要
境界を越える可能性のあるビジネスプロセスにはアクションベースのインテグレー
ションが適しています。データを移行することで将来のイノベーションを切り開き、
従来のシステムから脱却します。開発者は、トリガ、カスタムApex REST、データモデ
リングの外部 ID、キャンバスベースのカスタムクイックアクションについて理解する
必要があります。
接続デバイスのリアルタイムデータを分析する
動機
モノのインターネットとは、インターネットに接続されたスマートデバイスの次の波
を表す用語です。現在、インターネットに接続されたデバイスとして最も普及してい
るのは携帯電話とタブレットですが、車や自動販売機、さらに他のモノも、顧客の利
用状況や習慣に関する情報を企業に提供し始めています。ビジネスの将来は、あらゆ
るデバイスの背後に顧客が存在することを意識できるかどうかにかかっています。つ
まり、卓越した顧客サービスを提供するために、すべてのモノをビジネスに結び付
け、顧客の使用状況や習慣に関するデータを分析することが求められます。
16
第 1 章 Salesforce1 Platform の概要
戦略
接続デバイスの戦略は、非常に急速に発展しています。Salesforce1 には、堅牢なレポー
トおよびダッシュボード機能 (データを集計して、モバイルデバイスに表示する分析
API など) が用意されており、ユーザが情報に基づいてリアルタイムに意思決定を行う
ことができます。
接続デバイスを最大限に活用して顧客サービスの目標達成に役立てようとしている組
織は、顧客の利用状況や習慣に関するデータを効果的に処理する方法や、顧客とのコ
ミュニケーションに活用する方法に着眼する必要があります。
開発開始
通常、接続デバイスを使用する場合、物理デバイスをインターネットに接続するスペ
シャリストであるシステムインテグレータが必要になります。インターネットに接続
されたら、アプリケーション開発者が、デバイスから取得する情報のうち顧客サービ
ス要件に重要な情報を特定することに注力します。たとえば、開発者は、熱センサー
や、冷蔵庫の扉が開けられたことを示す信号、またはトラックの速度が特定のしきい
値を下回るタイミングなどの分析に重点を置きます。
データポイントを識別できたら、傾向を見極め、主要なワークフローの利用状況と顧
客からの即時の反応をサポートするアクションを分析するために、レポートとダッ
シュボードを作成する必要があります。
従業員の生産性を促進するモバイルアプリケーション
を作成する
動機
顧客がビジネス情報を必要とする場合に適時に正確に提供できなければ、どのような
システムを採用しても失敗に終わります。アプリケーションでは、このような情報を
提供するだけでなく、関連性が高い、状況に応じた、操作しやすい情報にすることが
求められます。
17
第 1 章 Salesforce1 Platform の概要
戦略
今日のビジネス環境では、データはモバイルデバイスで使用できるようにする必要が
あります。ただし、多くのエンタープライズモバイルアプリケーション戦略は、既存
のシステムを携帯電話やタブレットで再現しようとして失敗します。デバイスごと
に、ユーザによるデータのアクセス方法や操作方法が異なります。データは、ユーザ
の状況 (地理位置情報対応デバイスで特定される地理的状況およびユーザが操作して
いるレコードによって特定される組織的な状況の両方) に応じて提供される必要があ
ります。
フィード中心の検出、ソーシャルネットワークとのインテグレーション、およびアク
ションベースのワークフローにより、開発者は重要な情報を適時にモバイルデバイス
のユーザに配信でき、ユーザはタップやスワイプですぐにアクションを実行できるよ
うになります。
開発開始
まず、レコードに対するアクションを定義し、ユーザの代わりにデフォルト値を設定
できる領域を特定します。目的は、コンテキスト情報から取得できるデータを入力し
なくてもすむようにすることです。一般的な例として、地理位置情報、日付、ユーザ
名、および関連レコード情報 (取引先責任者の詳細や取引先名など) が挙げられます。
18
第 1 章 Salesforce1 Platform の概要
アクションを定義したら、毎日のユーザのアクティビティを調査してアプリケーショ
ンを作成します。それらのアプリケーションは Salesforce1 の左側のメニューに表示し
て 1 つのタブからアクセスできるように設定できます。
ID およびデータのセキュリティを境界を越えて展開す
る
動機
最新の ID 管理ソリューションは従来の境界ベースの認証よりも多くのことに対応する
必要があります。シンプルかつ信頼性の高い単一の方法で社内システム、クラウド
ベースのサービス、増加傾向にあるソーシャルおよびモバイルアプリケーションの認
証を管理することが求められます。
戦略
Salesforce1では、SAML や代理認証などの標準を使用して社内システムに接続できます。
これにより、組織は既存の ID ストアを柔軟に活用し、クラウドへと拡張することがで
きます。クラウドベースアプリケーションおよびカスタムモバイルアプリケーション
では、OAuth2 が安全にアプリケーションを認証および承認するための主要なメカニズ
ムになっています。Salesforce1には、堅牢な接続アプリケーションモデルが用意されて
おり、システム管理者がアプリケーション単位で権限を宣言して定義できます。
Salesforce1の強力なロール機能とプロファイル機能を組み合わせることで、システム管
理者は、ユーザが社内の認証トークンを使用して接続する場合でも、地球の裏側のモ
バイルデバイス上で実行されている接続アプリケーション経由で接続する場合でも、
どのレコードにどのユーザまたはユーザグループがアクセスできるかを制御できま
す。
19
第 1 章 Salesforce1 Platform の概要
開発開始
まず、アプリケーションに必要なデータから開始します。データの内容、データの
ソース、およびデータにアクセスできるユーザを定義します。データ要件を明確に理
解できたら、ユーザ ID のソースを計画します。組織に既存の ActiveDirectory 実装があり
ますか? シングルサインオンは重要ですか? 外部アプリケーションを Salesforce1 に接続
する予定がありますか?
20
第2章
Force.com の概要
Salesforce1 Platform のコアコンポーネントである Force.com は、カスタムアプリケーショ
ンの迅速な作成を支援するように設計されています。システム管理者やユーザは、直
観的なドラッグアンドドロップツール、強力なワークフローおよび承認エンジンなど
を使用してアプリケーションを作成できます。開発者や ISV は、プログラミングツー
ル、オープン API、および主要な言語とフレームワークを使用してアプリケーション
を作成できます。
Force.comが提供する API は、インテグレーションおよびデータアクセスアプリケーショ
ンの開発、組織のデータへのアプリケーションロジックの追加、カスタムユーザイン
ターフェースの作成や組織の既存のアプリケーションユーザインターフェースの統
合、Salesforce のソーシャル機能およびコラボレーション機能を使用するアプリケー
ションの開発に使用できます。サーバやソフトウェアの購入や管理が不要であるた
め、組み込みのソーシャルおよびモバイル機能、ビジネスプロセス、レポート、検索
を含むアプリケーションの作成のみに集中できます。アプリケーションはセキュアで
実証済みのサービス上で実行されます。また、サービスの拡張、調整、データのバッ
クアップは自動的に行われます。
Force.com には、次のインテグレーションおよびデータアクセス関連 API があります。
• SOAP API: Salesforce データにアクセスするための SOAP ベースの API。
• REST API: Salesforce データにアクセスするための REST ベースの API。
• メタデータ API: 組織のメタデータの管理と移行に使用される API。
• Bulk API: 大規模データセットの非同期読み込みおよびクエリのための REST ベースの
API。
• ストリーミング API: 組織のデータ変更の通知を効率よく管理するための転送技術
API。
• Salesforce Object Query Language (SOQL): 多くの Salesforce API で使用される、複雑なクエ
リの作成に使用されるクエリ言語。
• Salesforce Object Search Language (SOSL): 多くの Salesforce API で使用される、複雑なデー
タ検索の作成に使用される検索言語。
21
第 2 章 Force.com の概要
• Tooling API: カスタム Salesforce 開発ツールの作成に使用される REST および SOAP ベー
スの API。
• Salesforce1 レポート REST API: Salesforce のレポートデータの実行とアクセスに使用され
る REST ベースの API。
Force.com には、次のアプリケーションロジック関連機能があります。
• Apex: ビジネスロジック、トリガなどを組織のデータに追加するために使用可能な
オブジェクト指向のプログラミング言語。
Force.comには、次のユーザインターフェース開発およびインテグレーション関連機能
があります。
• Visualforce: Salesforce のアプリケーションやカスタムインターフェースの作成に使用
されるタグベースのマークアップ言語。
• Force.com Canvas: 既存の Web アプリケーションを直接 Salesforce に統合するために使
用されるツールとフレームワークのセット。
リソース
Force.com の各要素に関する包括的なドキュメントについては、Salesforce 開発者ドキュ
メント (http://developer.salesforce.com/docs) を検索してください。
22
第3章
Heroku の概要
Heroku は、Salesforce1 Platform のコアコンポーネントで、企業がすべての顧客向けアプ
リケーションの構築、提供および管理を行うことができるようにします。Salesforce1
API を使用すれば、アプリケーションでの顧客に関する深い洞察の獲得、コアビジネ
スシステムの統合と拡張、および企業と顧客のエンドツーエンドの接続を実現できま
す。Heroku は、このようなアプリケーションを実行するのに最適です。
この章では、Heroku を使用して、顧客向けアプリケーションを構築、リリース、およ
び拡張する方法について説明します。バックエンドには Salesforce1 API を活用し、迅速
かつ高品質なアプリケーションを提供するために Heroku のスイート (強力な開発者ツー
ルおよび最新のクラウドサービス) を活用します。
アプリケーションは顧客にリーチするための新しいチャネルです。これにより、企業
はモバイル顧客、ソーシャル顧客およびつながっている顧客に場所やデバイスに関係
なくリーチできる、状況に応じたインタラクティブな操作性を作り出すことができま
す。現在の企業には、堅牢な API、コアビジネスシステム、および豊富な顧客データ
を活用するだけでなく、顧客向けアプリケーションや新機能の迅速な提供、モバイル
デバイスや接続デバイスへの最適化、トラフィックの急増や新規ユーザ受け入れのた
めの効率的な拡張が求められています。
次に、Salesforce1 API と Heroku のアプリケーション提供プラットフォームを融合して、
カスタマイズされた魅力的な操作性をユーザに提供するアプリケーションの例を示し
ます。
• 顧客エンゲージメント — これらのアプリケーションは、魅力的なアプリケーショ
ン体験を通じて企業と顧客を結び付けます。Heroku プラットフォームでは、主要な
イベントや商品の発売に関連するマーケティングキャンペーン、バイラルキャン
ペーン、獲得キャンペーン、ロイヤルティキャンペーン、コンシューマ購入フ
ロー、ソーシャルアプリケーション、コンテンツプラットフォーム、革新的な接
続デバイスアプリケーションなどの優れた顧客エンゲージメントアプリケーショ
ンがリリースされています。これらのアプリケーションにより企業は新しい市場
に到達でき、新らたな顧客層やターゲット層を縦横に拡大することができます。
• コンシューマモバイル — 今日の企業は競争力を維持するために、現在つながって
いるコンシューマの多数の画面でブランド、サービスおよび商品を展開できる必
23
第 3 章 Heroku の概要
要があります。モバイルアプリケーションでは、場所に関係なく、顧客のすべて
のモバイルデバイス、そして顧客が所有するつながる製品、ゲームコンソール、
テレビ、さらには車でも、関連性の高いエンゲージメントを実施できます。これ
らのアプリケーションを使用することでブランドロイヤルティを構築できます。
顧客は、任意のデバイスからの閲覧および購入、重要なデータへのアクセス、通
知の受信、企業との対話や交流をどこでも行うことができるようになり、実店舗
に引けを取らない体験を実現できます。また、これらのアプリケーションでは、E
コマースからビジネスインタラクション (予約や注文状況の確認など) まで、セル
フサービス環境を強化することもできます。
• Force.com + Heroku — これらのアプリケーションは、Salesforce 組織内に保存された
豊富な顧客データを通じて企業と顧客を結び付けます。インテリジェントデータ
と統合することで、企業は各状況に対応できるフルカスタム顧客アプリケーショ
ンを構築したり、ビジネスプロセスを自動化したり、データを取得したり、Heroku
Connect を使用してすべてをコアビジネスシステムに結び付けたりできます。
Heroku について
Heroku は、開発者の生産性向上のためにゼロから設計されており、インフラストラク
チャ、運用、および拡張性の管理の負担が軽減されるため、開発者や開発チームは優
れたアプリケーションを顧客に提供することに集中できます。Heroku では、迅速なリ
リース、合理的なワークフロー、完全に管理されたクラウドサービスのマーケットプ
レイス、アプリケーション開発のための組み込みのベストプラクティスを提供しま
す。これらはすべて、アプリケーションの実行および管理を行う、拡張性と信頼性の
高い単一のプラットフォームで実現できます。
Heroku には、アプリケーションに不可欠な次のようなツールおよびビルディングブ
ロックが用意されています。
• Node.js、Java、Python、Ruby、および PHP のサポート。これにより、開発チームは、
すでに理解している言語ですぐに高い生産性を確保できます。
• Heroku Connect。これにより、データを Salesforce 環境と共有する Heroku アプリケー
ションを簡単に作成できます。Heroku Connect は、Salesforce と Heroku Postgres の間の
双方向の同期を使用して、Postgres データベース内のデータを Salesforce データベー
ス内の取引先責任者や取引先、他の標準オブジェクトおよびカスタムオブジェク
トと統合するため、Force.com と Heroku プラットフォームの機能を簡単に組み合わ
せることができます。
24
第 3 章 Heroku の概要
• 単一のコマンドで追加および拡張できる、完全に管理されたサービス (監視、ログ
記録、保持、キャッシュ、メール配信などのサービス) の堅牢なオンデマンドアド
オンマーケットプレイス。アドオンを使用すると、基盤となるインフラストラク
チャを管理することなく、Redis、MongoDB、PubNub、Mailgun、Hadoop などの最高ク
ラスのテクノロジを簡単に提供および使用できます。
• 不可欠なモバイルアプリケーションインフラストラクチャのモバイルバックエン
ドサービス (転送通知、データの同期、アプリケーション内の購入など)。
• Heroku Postgres (継続的な保護、自動化されたヘルスチェック、シンプルな設定、参
照のみのレプリカの簡単な設定、強力なクエリ機能でデータに集中できるように
する、サービスとしての SQL データベース)。
Heroku は、単なるインフラストラクチャプロバイダではなく、ライフサイクルの各
フェーズで開発者の生産性とアプリケーションの保守性を最大化するためにゼロから
設計された開発者の生産性プラットフォームで、次のような特徴を備えています。
• 迅速かつ継続的な提供を実現するために、Git を使用してリリースしたり、ステー
ジング環境、開発環境、および本番環境を簡単に作成したりできる効率的で安全
なワークフロー
• 発展に合わせてアプリケーションのスケールアップができるシンプルで強力なモ
デル
• 簡単で直感的なインターフェースおよびツール (強力なコマンドラインインター
フェースや合理化されたダッシュボードなど)
• チーム、拡張チームおよびサードパーティパートナー (アプリケーション開発会社
など) 間で効率的な作業を行うための組み込みのコラボレーション
• すべてのアプリケーションの一元的な請求および管理
Heroku の主要な機能
このセクションでは、Heroku の不可欠な機能と基本概念、およびアプリケーションで
の活用方法に関するツアーを提供します。このセクションでは、実行やリリース、ア
ドオンマーケットプレイス、Heroku Postgres、プラットフォームのワークフローやコラ
ボレーションについて説明します。
25
第 3 章 Heroku の概要
リリース、実行、および拡張
Heroku は、アカウントのサインアップを行い、Toolbelt (Heroku CLI やその他の不可欠な
ツールをインストールするスタートパッケージ) をインストールするだけで簡単に開
始できます。Heroku では、理解している言語 (標準の Ruby、Node.js、Python、PHP、Java
をサポート) でアプリケーションを作成できます。アプリケーションをリリースする
準備が整ったら、Git を使用してコードを Heroku に転送します。Heroku は、アプリケー
ションの連動関係、バイナリおよびアセットを取得してコンパイルし、指定の設定を
適用して、そのプロセスを実行します。アプリケーションはすぐに起動して実行さ
れ、任意のブラウザやデバイスから固有の URL でアクセスできるようになります。も
ちろん、開始する準備が整ったら、カスタムドメインを簡単に適用できます。プロビ
ジョニング、運用、セキュリティ、アップグレードは salesforce.com が対応するため、
インフラストラクチャを管理する必要がなくなり、アプリケーションに集中できま
す。
Heroku では、迅速かつ効率的で調整可能な拡張をサポートする、シンプルで強力なプ
ロセスモデルが使用されます。「dyno」は、Heroku の拡張の基本単位です。dyno は、
ユーザ指定の単一のコマンドを実行する軽量な仮想コンテナです。dyno は、web、
worker、queue、およびアプリケーションを強化するために必要なその他のプロセスを
実行します。dyno は、発展に合わせて個別にオンデマンドでスケールアップできま
す。スケールアップには、Heroku CLI または Heroku ダッシュボード (Web ベース UI) が使
用されます。
アプリケーションは、アプリケーションのメモリや同時要件に応じて 1 つ以上の dyno
で構成されます。Heroku には、3 つの dyno サイズが用意されています。
• 1x dyno は Heroku のデフォルトで、各 dyno で 512 MB のメモリと 1x CPU 共有が提供さ
れます。
• 2x dyno では、1x dyno の 2 倍のメモリと CPU 共有 (合計で 1024 MB のメモリと 2x CPU
共有) が提供されます。2x dyno は、メモリを大量に消費するアプリケーションや高
度な同時実行が必要なアプリケーションに最適です。
• PX dyno は、8 つのコアを搭載し、高い独立性と優れたパフォーマンス特性を持ち
ます。PX dyno では、6 GB のメモリと専用のコンピュート環境が提供されます。
アプリケーションは dyno 単位で拡張でき、新しいリソースは数秒以内にアプリケー
ションに提供されるため、アプリケーションの柔軟性と管理性が大幅に向上します。
たとえば、さらに多くの Web トラフィックに対応する必要がある場合、web dyno の数
26
第 3 章 Heroku の概要
を増やすだけですみます。Heroku がルーティングやその他の追加の操作に対応しま
す。
アドオン
もちろん、ピーク時、ウイルスに関連するイベント、ユーザの増加、新機能の追加な
どのイベントに応じて、オンデマンドで dyno をスケールアップまたはスケールダウン
できます。ただし、アプリケーションの需要増加を適切に予測して対応できるよう
に、自動拡張サービスや最高レベルの監視システムが必要になる場合があります。
Heroku には、コアアプリケーションインフラストラクチャを実行するための拡張性の
高いオンデマンドインフラストラクチャが用意されていますが、それだけではなく、
アドオンマーケットプレイスの最高品質のテクノロジを使用して簡単にアプリケー
ションを拡張することもできます。マーケットプレイスには、完全に管理された 100
を超えるクラウドサービスがあります。このクラウドサービスは、各分野のエキス
パートによって運用され、Heroku に直接統合されます。
アドオンは、トッププロバイダによって完全に管理された、Heroku に統合されるサー
ドパーティサービスであるため、アプリケーションで簡単に追加、拡張、および使用
できます。アドオンは 1 つのコマンドで追加できます。また、小規模なデモアプリ
ケーションやサンプルプロジェクトから大規模な本番アプリケーションまで、あらゆ
るサイズのアプリケーションに対応できるように、さまざまな価格の豊富なプランで
提供されます。これらのアドオンの多くは、すでに開始されている発展中のアプリ
ケーションに特定に必要なサービス (監視、保持、ログ記録、キャッシュなど) を提供
しています。次に、いくつか例を示します。
• 保持: 状態の保持、管理、および拡張は、本番アプリケーションの最優先事項の 1
つです。Heroku アドオンマーケットプレイスでは、さまざまなデータストレージソ
リューションが提供されているため、ニーズに最適なデータストアタイプを簡単
に統合できます。リレーショナルデータベース、非リレーショナルデータベース、
グラフデータベース、分析ソリューション (Postgres、MongoDB、Neo4j、Hadoop など)
などのアドオンがあります。
• キャッシュ: キャッシュは、アプリケーションの応答時間やユーザエクスペリエン
スを大幅に改善するため、Web およびモバイルのパフォーマンス向上には不可欠
です。キャッシュアドオンとして、memcache を本番アプリケーションに追加でき
る MemCachier、memcache プロトコルをサポートする IronCache、および Ruby on Rails
アプリケーションのラックミドルウェアである Cachely などが挙げられます。
27
第 3 章 Heroku の概要
• 監視: 監視を行うことで、問題を検出するとともに、経時的な重要指標を把握でき
るため、安心感が得られます。Heroku のアドオンマーケットプレイスには New Relic
があります。これは、最も有名なアドオンの 1 つで、すばやく起動して実行できる
ように、自動的にプライベート New Relic アカウントを作成して、アプリケーショ
ンへのアクセスを設定します。ダッシュボードのカスタマイズを考えているユー
ザには、直接アプリケーションログからすぐにデータを設定して使用できる Librato
があります。
• ログ記録: ログは、トレンド分析、エラー検査、パフォーマンス調整、および本番
アプリケーションの実行に不可欠なその他のプロセスの基盤となります。Heroku
は、アプリケーションの各部分 (実行プロセス、システムコンポーネント、API イベ
ント、アドオン自体など) のリアルタイムログをルーティングおよび整理します。
ログストリームを使用し、保持、検索、アラート、およびその他のサービスとの
インテグレーションのような高次サービスを提供するアドオン (Papertrail、Logentries、
Loggly、Flydata など) がいくつか用意されています。
• その他: アドオンには、主要なエンゲージメント機能を顧客に提供するサービス
(メール配信、電話サービス、転送通知、ビデオエンコーダ、支払いなどのサービ
ス) があります。StatusPage、Zencoder、PandaStream、Blitz、Pusher、PubNub などのプ
ロバイダのアドオンを選択できます。
Heroku Postgres
Heroku Postgres は、Heroku のサービスとしてのデータベース (database-as-a-service) 製品で、
Heroku アプリケーションの Postgres データベースのプロビジョニングおよび拡張を簡
単に実行できます。Heroku Postgres には、継続的な保護、自動化された健全性チェッ
ク、「followers」(データベースの参照のみのレプリカを簡単に設定できるようにする)、
各種言語の簡単な設定、コマンドラインツール、アプリケーションフレームワークな
どの多数の機能があります。また、Heroku Postgres の「fork」機能を使用して、バイト
レベルの完全なデータベースコピーを作成し、テスト、負荷実験、および新しいス
キーマの安全な移行などに使用できます。
Heroku Postgres に保存されたデータは、アプリケーションからのアクセス以外でも重要
です。格納されたアプリケーションデータおよびユーザデータはコアビジネスに不可
欠な上、ユーザがこれらのデータにアクセスする必要があります。Heroku Postgres は、
この目的を達成するために、社内でデータのアクセス、クエリ、および共有を簡単に
行うことができるようにします。Dataclips (Heroku Postgres のすべての本番データベース
28
第 3 章 Heroku の概要
および初期データベースで使用可能) により、データに対して SQL クエリを実行し、簡
単かつ視覚的な方法で結果をチームメンバーと共有できます。
Dataclips は、URL 経由でダウンロードや共有ができます。また、多数のダウンロード形
式およびエクスポート形式がサポートされており、データの安全性を確保するために
参照のみのトランザクションを介して実行されます。これにより、ビジネスを促進さ
せるデータを安全かつ簡単に取得および共有できます。
Heroku Connect
Heroku Connect は、Salesforce および Heroku Postgres 間の、双方向のデータ同期を提供しま
す。Heroku Postgres で Salesforce データを使用すると、Force.com と Heroku のプラットフォー
ムの機能を簡単に組み合わせることができます。
Rails、Node.js、Java、PHP、および Python などの標準的なオープンソース言語とスタッ
クを使用して作成されたアプリケーションは、Postgres とネイティブに接続し (Heroku
Connect 経由)、直接 Salesforce に戻ります。
これにより、Heroku の SQL やコードを使用してSalesforceのデータを処理したり、Heroku
アプリケーションで取得したコンシューマのデータをSalesforce組織にシームレースに
戻したりといった、多くの新しい機会が広がります。
Workflow
Heroku は、アプリケーションの実行に必要なコアインフラストラクチャだけでなく、
生産性を最大化して市場投入までの時間を短縮する、迅速かつ効率的な開発者ワーク
フローを設定するための多数の機能も提供します。Heroku のアプリケーションの fork
機能を使用すれば、同機種のステージング環境、開発環境および本番環境で標準化さ
れた現実的なワークフローを簡単に設定できます。これにより、安全にコードを開発
およびテストし、準備が整ったときに本番環境に昇格させることができます。また、
Heroku アドオンマーケットプレイスの継続的インテグレーションアドオン (Travis CI や
CircleCI など) で、開発ワークフローをさらに改善できます。
コラボレーション
コラボレーションは、開発者の生産性向上に不可欠です。多くの場合、顧客向けアプ
リケーションは、製品マネージャ、エンジニアリングマネージャ、リモート従業員、
アプリケーション開発業者およびコンサルタントなどが含まれる拡張アプリケーショ
29
第 3 章 Heroku の概要
ン開発チームの製品になります。Heroku では、アプリケーションチームの複雑で変化
する構成およびベロシティに対応するために、簡単にコラボレータをアプリケーショ
ンに追加して共同作業ができるようになっています。コラボレータは、アプリケー
ションへのアクセス、コードの転送、変更のプルダウンおよびマージをすぐに実行で
きます。後で権限を取り消す必要がある場合も、簡単に実行できます。コラボレー
ションは Heroku のあらゆる部分に組み込まれており、Heroku ダッシュボードからすべ
てのコラボレータを表示および管理できます。また、Heroku の包括的なログ記録シス
テムはコラボレータを追跡するため、アプリケーションに対するアクションの全履歴
を簡単に確認できます。これは、リリースなどの特定のイベントにドリルダウンする
場合に特に便利です。
表示とアプリケーションの管理
今日のビジネスにおいて、可視性とアプリケーションの管理は、効率的なビジネスの
運用やアプリケーションの提供に不可欠です。Heroku では、単一のインターフェース
で、dyno からアドオンまですべてのアプリケーションリソースの一元的な請求および
管理ができます。
ブラウザから Heroku にサインインすると、Heroku ダッシュボードが表示されます。
ダッシュボードは、Heroku のすべてのアプリケーションのパーソナライズされたイン
タラクティブなコマンドセンターです。ダッシュボードでは、アプリケーションの状
況、アクティビティ、リソース、アドオン、コラボレータ、およびアプリケーション
のその他の不可欠な要素のシンプルな表示と管理が可能です。また、Heroku アカウン
トに関するすべての情報 (SSH キーや過去の請求書など) を管理するために使用するこ
ともできます。さらに、ダッシュボードを使用して、アプリケーションの本番稼働状
況のチェックも実行できます。本番稼働状況のチェックでは、可用性の維持および監
視のために推奨される一連のテスト (適切な DNS 設定、dyno の冗長性、およびアプリ
ケーションやログの監視など) がアプリケーションに対して実行されます。
Heroku の可視性について議論するには、Heroku のログ記録をさらに詳しく説明する必
要があります。ログでは、アプリケーションの履歴 (イベント、変更および動作の実
際の連続的なストリーム) がわかります。ログにより、重大なイベントをすばやく特
定して対応したり、コードの問題をデバッグしたり、長期にわたり適切な決定をする
ためのトレンドを分析したりできます。
Heroku では、ログ記録が簡素化および整理されます。Heroku では、アプリケーション
の各部分から単一のチャネルにログが自動的に整理およびルーティングされます。こ
れにより、非常に包括的で拡張可能なアプリケーション中心のログ記録が実現しま
30
第 3 章 Heroku の概要
す。ログストリーム向けに豊富なコマンドライン機能が用意されています。このコマ
ンドライン機能は、他のサービスに簡単にプラグインでき、ログ管理の手間を軽減し
ます。Logplex は、Heroku プラットフォーム、API ログ (ユーザやコラボレータが実行し
た管理アクションを含む)、出力 (アプリケーション内、アプリケーションサーバ、イ
ンストールされたライブラリ、およびストリームを公開するように設定されたバッキ
ングサービスからの出力) から基盤となるイベントを収集します。これにより、アプ
リケーションの完全な履歴 (Heroku の各部分、アプリケーションの各コンポーネント、
そのすべてのプロセス、およびユーザやチームメイトが行ったすべての変更のログ)
が記録されます。
信頼性の高いオープンプラットフォーム
Heroku は、10 万を超える顧客から信頼されている No.1 のエンタープライズクラウドコ
ンピューティングプラットフォームである Salesforce1 の一部です。400 万を超えるアプ
リケーションが Heroku にリリースされています。Heroku はオープンであり、オープン
ソースコンポーネント上に構築されています。Heroku ビルドパック (Heroku で実行でき
るようにコードの準備を行うスクリプト) はすべて、他のクラウドプラットフォーム
でサポートされている拡張可能なオープンソースで、最大限の移植性が確保されてい
ます。Heroku では、標準的なツールおよび言語 (Git、主要なすべての言語の標準バー
ジョン、Postgres、WebHooks、およびその他のオープンソーステクノロジの標準実装)
がサポートされています。また、Heroku にはプラットフォーム API も用意されていま
す。これによって、サードパーティ開発者は Heroku プラットフォームの自動化、拡
張、および他のサービスとの統合をプログラムによってセルフサービス形式で行うこ
とができます。つまり、継続的インテグレーションツールや、Heroku アプリケーショ
ンを管理するモバイルアプリケーションのようなサードパーティビジネスおよびサー
ビスを構築できます。
Heroku クイックスタート
このセクションでは、Heroku への最初のアプリケーションのリリースを開始する方法
について説明します。説明のために Ruby アプリケーションを例として使用します。ア
プリケーションをリリースするプロセスは、Heroku でサポートされているどの言語
(Ruby、Python、Node.js、Java) でもほとんど同じです。ただし、言語の標準や構造によ
る若干の違いがある場合があります。言語に固有の詳細は、
https://devcenter.heroku.com/quickstart を参照してください。
31
第 3 章 Heroku の概要
ステップ 1: サインアップする
まず、Heroku.com に移動して [サインアップ] をクリックし、無料の Heroku アカウント
を取得します。無料のアカウントと共に、開始するための無料の dyno 時間を得られま
す。
ステップ 2: Heroku Toolbelt をインストールする
Heroku Toolbelt には、Heroku クライアント (Heroku アプリケーションを作成および管理す
るためのコマンドラインツール)、Foreman (アプリケーションをローカルで実行するた
めの簡単なオプション)、および Git (Heroku にアプリケーションを転送するために必要
なリビジョン管理システム) が含まれています。
Heroku Toolbelt には、スタンドアロンパッケージのほかに、Mac OS X、Windows、および
Debian/Ubuntu 用のパッケージが用意されています。
ステップ 3: コマンドラインからログインする
Toolbelt をインストールしたら、コマンドシェルから heroku コマンドにアクセスでき
ます。
Heroku アカウントの作成時に使用したメールアドレスとパスワードを使用して認証し
ます。以前にキーを Heroku にアップロードしている場合、そのキーを使用し続けると
想定されるため、ログイン中に新しいキーを作成するように求められることはありま
せん。
プロンプトで Enter キーを押して、既存の ssh キーをアップロードするか、新しいキー
を作成します。このキーは、後でコードを転送するときに使用します。
$ heroku login
Enter your Heroku credentials.
Email: [email protected]
Password:
Could not find an existing public key.
Would you like to generate one? [Yn]
32
第 3 章 Heroku の概要
Generating new SSH public key.
Uploading ssh public key /Users/adam/.ssh/id_rsa.pub
ログイン後に新しいキーを作成してアップロードする場合、単に heroku keys:add
を実行します。
ステップ 4: アプリケーションのリリースの準備をす
る
これで、Heroku にアプリケーションをリリースする準備が整いました。既存のアプリ
ケーションがない場合、オンラインの開発センターにある「Hello World!」サンプルを
利用できます。
Heroku は、Gemfile が存在していれば、アプリケーションが Ruby で記述されていると判
断します。Heroku が、pom.xml ファイル (Java)、requirements.txt (Python)、および package.json
(Node.js) を検索します。
アプリケーションを Heroku にリリースする前に、あといくつかの作業 (連動関係の宣
言、プロセスタイプの宣言、ローカルでのアプリケーションのテスト、Git へのコード
のコミット) を行う必要があります。
まず、連動関係 (システムレベルの連動関係は除く) を宣言する必要があります。アプ
リケーションをローカルでテストし、アプリケーションと連動するすべての gem が
Gemfile にあることを確認します。使用する Ruby のバージョンを忘れずに指定してくだ
さい。Heroku では、デフォルトで Ruby 2.0 がサポートされていますが、整合性を確保
するためにすべてのアプリケーションでバージョンを指定する必要があります。
次に、Procfile でプロセスタイプを宣言する必要があります。Procfile は、dyno を起動す
るために実行する必要のあるコマンドを明示的に宣言するテキストファイルで、アプ
リケーションのルートにあります。このファイルには、web、worker、またはその他の
プロセスが含まれます。この例では、web dyno を開始します。
web: bundle exec ruby web.rb -p $PORT
これは、単一プロセスタイプ web と、web を実行するために必要なコマンドを宣言し
ています。ここでは、「web」という名前が重要です。これは、このプロセスタイプ
33
第 3 章 Heroku の概要
が Heroku の HTTP ルーティングスタックに関連付けられ、リリース時に Web トラフィッ
クを受信することを宣言しています。
この時点で、Foreman (Procfile 対応アプリケーションを実行するためのコマンドライン
ツール) を使用して、ローカルでアプリケーションを実行できます。Foreman は、Heroku
Toolbelt と共にインストールされています。
foreman start を実行するだけでポート 5000 でアプリケーションが起動されるた
め、確認します。
最後に、アプリケーションファイルをローカルの Git リポジトリにコミットします。
$ git init
$ git add
$ git commit -m "init"
ステップ 5: リリースする
これで、Heroku にアプリケーションをリリースする準備が整いました (負荷の高い作業
は完了しました)。
まず、heroku create コマンドを使用して Heroku にアプリケーションを作成します。
$ heroku create
Creating blazing-galaxy-997... done, stack is cedar
http://blazing-galaxy-997.herokuapp.com/ |
[email protected]:blazing-galaxy-997.git
Git remote heroku added
次に、git push heroku master コマンドを使用して、Git でアプリケーションをリ
リースします。
$ git push heroku master
Counting objects: 6, done.
Delta compression using up to 4 threads.
34
第 3 章 Heroku の概要
Compressing objects: 100% (5/5), done.
Writing objects: 100% (6/6), 660 bytes, done.
Total 6 (delta 0), reused 0 (delta 0)
-----> Ruby/Rack app detected
-----> Using Ruby version: ruby-2.1.2
-----> Installing dependencies using Bundler version 1.3.2
Running: bundle install --without development:test --path
vendor/bundle --binstubs vendor/bundle/bin --deployment
Fetching gem metadata from https://rubygems.org/..........
Fetching gem metadata from https://rubygems.org/..
Installing rack (1.2.2)
Installing tilt (1.3)
Installing sinatra (1.1.0)
Using bundler (1.3.2)
Your bundle is complete! It was installed into ./vendor/bundle
Cleaning up the bundler cache.
-----> Discovering process types
Procfile declares types
-> web
Default types for Ruby/Rack -> console, rake
-----> Compiled slug size: 25.1MB
-----> Launching... done, v3
35
第 3 章 Heroku の概要
http://blazing-galaxy-997.herokuapp.com deployed to Heroku
To [email protected]:blazing-galaxy-997.git
* [new branch]
master -> master
この例では、http://blazing-galaxy-997.herokuapp.com で Web ブラウザにアプリケーション
を表示したり、curl を使用してテストしたりできるようになります。
これで、最初のアプリケーションを Heroku にリリースできました。
ステップ 6: CLI を使用する
Heroku CLI を使用して、アプリケーションの操作 (統合ログの表示、アプリケーション
の拡張、アドオンサービスの追加) を行うことができます。
Web トラフィックをスケールアップする場合、web dyno の数を調整するように Heroku
に通知するだけですみます。
$ heroku ps:scale web=2
Scaling web dynos... done, now running 2
実行されている dyno の数を確認します。
$ heroku ps
git:master
=== web (1X): `bundle exec ruby web.rb -p $PORT`
web.1: up 2013/10/15 11:28:17 (~ 5m ago)
web.2: up 2013/10/15 11:33:24 (~ 1s ago)
発生したすべての新規ログイベントが表示されるように tail を指定して、統合ログス
トリームを表示します。
$ heroku logs --tail
2013-10-15T10:24:25.602652+00:00 app[web.1]: Started GET
36
第 3 章 Heroku の概要
"/articles/getting-started-with-nodejs" for 84.32.143.141 at 2013-10-15
10:24:25 +0000
2013-10-15T10:24:25.885004+00:00 heroku[router]: at=info method=GET
path=/assets/public/feed-icon-sprite.png host=devcenter.heroku.com
request_id=fd511f6195f52e8e58f58cccbc07109c fwd="77.252.246.255"
dyno=web.12 connect=0ms service=15ms status=200 bytes=4867
2013-10-15T10:24:26.563176+00:00 heroku[web.1]: source=web.1
dyno=heroku.12227120.90edce79-b91e-403e-be3f-2f2ba11aa5af
sample#load_avg_1m=0.00 sample#load_avg_5m=0.00 sample#load_avg_15m=0.00
…
重大なイベントに関するログを保持してアラートを送信する必要がある場合、多数の
ログ記録アドオン (Papertrail など) のいずれかを追加します。
$ heroku addons:add papertrail
Adding papertrail on blazing-galaxy-997... done, v6 (free)
Use `heroku addons:docs papertrail` to view documentation.
効率性と生産性の高い開発者ワークフローを設定する必要がある場合、Heroku では、
アプリケーション全体に fork を実行できるため、同一のステージング環境を簡単に構
築できます。
$ heroku fork staging-galaxy
Creating fork blazing-galaxy-997... done
Copying slug... done
Copying config vars... done
Fork complete, view it at http://staging-galaxy.herokuapp.com/
これで、ソースの新しいブランチをこの新規アプリケーションにリリースできます。
$ heroku git:remote -a staging-galaxy -r staging
git:master
37
第 3 章 Heroku の概要
Git remote staging added
$ git push staging newbranch:master
カスタムドメインで起動する準備はできましたか。DNS および CNAME を設定すれば、
簡単に実行できます。
$ heroku domains:add www.mydomain.com
Adding www.mydomain.com to blazing-galaxy-997... done
Heroku では、設定とコードが分離されているため、アプリケーションに影響する可能
性のある値 (秘密鍵など) を簡単に変更できます。
$ heroku config:set SECRET_KEY=2342434434343433555422
Setting config vars and restarting blazing-galaxy-997….done, v8
リリース履歴にドリルダウンして、ベロシティ、最新の変更、またはトラブルシュー
ティングの問題に関する詳細情報を取得する必要がある場合、これに対応するコマン
ドも用意されています。
$ heroku releases
=== demo-for-james Releases
v6
Add SECRET_KEY config
2013/10/15 12:00:10 (~ 59s ago)
[email protected]
v5 Add papertrail:choklad add-on
2013/10/15 11:26:59 (~ 34m ago)
[email protected]
v4 Deploy 9579f23
2013/10/15 10:23:32 (~ 1h ago)
[email protected]
v3 Deploy 0eb78aa
2013/10/15 10:21:33 (~ 1h ago)
[email protected]
v2 Enable Logplex
2013/10/15 09:58:21 (~ 2h ago)
[email protected]
v1 Initial release
2013/10/15 09:58:20 (~ 2h ago)
[email protected]
38
第 3 章 Heroku の概要
問題を修正するために以前のリリースにロールバックします。
$ heroku rollback v6
Rolling back blazing-galaxy-997... done, v6
!
Warning: rollback affects code and config vars; it doesn't add
or remove addons. To undo, run: heroku rollback v7
Heroku から Salesforce1 API をコンシュームする場
合のベストプラクティス
Salesforce 組織の機能を拡張するためのアプリケーションを作成するとします。OAuth
を使用すると、アプリケーションがプラットフォームで認証されます。ユーザは、そ
のアプリケーションがユーザの代わりにアクションを実行できるように、Salesforce ロ
グイン情報を使用して認証することができます。OAuth のログイン情報の設定手順は、
認証 (ページ 49)を参照してください。ここでは、Heroku で OAuth を安全に管理する方
法を説明します。
Heroku でアプリケーション開発に適用されるセキュリティベストプラクティスの 1 つ
は、設定情報 (ログイン情報など) をコードから分離することです。これにより、パス
ワードなどの機密情報が、ソースコードの保存場所や開発用コンピュータから不用意
に拡散することを防止できます。また、設定情報をコードから分離すると、アプリ
ケーションのリリースごと (ステージングと本番など) に設定を独立して管理すること
もできます。通常のアプリケーションはその段階が進むごとにリリースが増えていく
ので、これは、それに合わせて円滑に拡張できるモデルです。
こうした理由から、Heroku では設定 (OAuth コンシューマ鍵やコンシューマの秘密など)
を設定変数に保存し、鍵をコードから分離します。Heroku では、これらの設定変数が
アプリケーションに対する環境変数として表されます。これらの環境変数は永続的で
す。つまり、異なるリリース間やアプリケーションの再起動前後でも変わることはあ
りません。そのため、値を変更する必要がない限り、設定が必要なのは 1 回だけで
す。
Salesforce での認証のためにアプリケーションの OAuth ログイン情報を管理する方法の
例を次に示します。
39
第 3 章 Heroku の概要
最初に、OAuth のコンシューマ鍵とコンシューマの秘密の設定を定義します。
$ heroku config:set
OAUTH_ID=3MRG8lKcPoNINVBJSoQsNCD.HHDdbugPsNXwwyFbgb47KWa_ABc
Adding config vars and restarting myapp... done, v12
OAUTH_ID: 3MRG8lKcPoNINVBJSoQsNCD.HHDdbugPsNXwwyFbgb47KWa_ABc
$ heroku config:set OAUTH_SECRET=5678471853609579511
Adding config vars and restarting myapp... done, v13
OAUTH_SECRET: 5678471853609579511
これで、コマンドラインからいつでも設定の取得、設定の削除、または変更ができま
す。
$ heroku config:get OAUTH_ID
3MRG8lKcPoNINVBJSoQsNCD.HHDdbugPsNXwwyFbgb47KWa_ABc
$ heroku config:unset OAUTH_ID
Unsetting OAUTH_ID and restarting myapp... done, v14
Heroku でアプリケーションの設定変数にコンシューマ鍵とコンシューマの秘密を設定
したら、アプリケーションは OAuth ロジックを実装して、適切な Salesforce 認証エンド
ポイントに対して OAuth 認証フローを実行できます。他の環境変数の場合と同様に、
アプリケーション内から設定変数にアクセスするだけです。
リソース
Heroku に関する詳細情報を取得するには、次のリソースを使用します。
• Heroku 開発センター: https://devcenter.heroku.com
• Heroku の使用開始: https://devcenter.heroku.com/articles/quickstart
• Heroku Connect: https://www.heroku.com/connect
40
第4章
ExactTarget の概要
Salesforce1 Platform のコアコンポーネントである ExactTarget Fuel は、世界でもトップレベ
ルの多くのブランドのマルチチャネルマーケティングプログラムでその実力を発揮し
ています。ExactTarget Marketing Cloud の基盤である Fuel は、サードパーティ開発のため
にオープンとなっています。ExactTarget の業界最高レベルのデジタルマーケティング
製品をベースとした構築、拡張、統合が可能です。
Fuel には次をはじめとするテクノロジが結集されています。
• API: Fuel の API は salesforce.com のプラットフォームの基盤です。Fuel には SOAP API と
REST API が用意され、クラウド開発とエンタープライズ開発のシナリオに対応しま
す。
• SDK: Fuel のソフトウェア開発キット (SDK) があれば、開発者はネイティブ言語の構
成要素を使用して ExactTarget と統合できます。Fuel SDK は、Java、.NET、PHP、Python、
Ruby 向けに提供されています。
• Fuel UX: Fuel UX は、ExactTarget Marketing Cloud や ExactTarget の Marketing Cloud アプリケー
ションで使用するユーザインターフェースツールキットです。Bootstrap、jQuery、
41
第 4 章 ExactTarget の概要
RequireJS などの先駆的なオープンソースの JavaScript テクノロジに基づく Fuel UX に
より、Marketing Cloud のデザインと密接に統合するアプリケーションを簡単に構築
できます。
• データ拡張: データ拡張は、ほとんどすべてのデータ型の柔軟なテーブルであり、
パーソナライズ設定やセグメント化に使用したり、送信元データソースとして使
用したりできます。データ拡張は強力な構造になっており、クラウドベースのマー
ケティングリレーショナルデータベースとみなすことができます。
• AMPscript: AMPscript は Marketing Cloud のコンテンツスクリプト言語であり、メール、
SMS メッセージ、ランディングページのコンテンツをプログラムでパーソナライズ
するために使用できます。AMPscript とデータ拡張は連動できるため、メッセージ
のデータ拡張からデータを読み取り、ランディングページのデータ拡張にデータ
を書き込むことができます。
• シングルサインオン: Fuel では、ExactTarget Marketing Cloud とそのアプリケーションを
対象としたシングルサインオン環境が提供されます。この環境は、2 要素認証、IP
ホワイトリスト登録、IP ブロック、リアルタイムのアラートおよび監視を含む (た
だしこれらに限定されない) 複数のセキュリティで保護されています。
Fuel で何ができるのでしょうか。ユーザは、Fuel を使用してマーケティングキャンペー
ン全体を自動化したり、ExactTarget アプリケーションを各自のニーズに合わせてカス
タマイズしたり、ExactTarget をマーケティングや分析などさまざまなビジネスソフト
ウェアに統合したりすることができます。パートナーは、Fuel を使用してマーケティ
ングアプリケーションを構築または拡張し、それらを Salesforce のプラットフォーム関
連パートナープログラムを通じて ExactTarget と合わせて販売することができます。
次のセクションでは、許可、パーソナライズ、データなど、顧客との接触を成功させ
るための基本的な概念を挙げ、開発者がテクノロジを利用して個々の顧客に働きかけ
る機会について説明します。
開発者にとっての顧客タッチポイント
送信されるメールや配信されるメッセージそして通知は、1 つ 1 つがすべて異なるも
のです。クレジットカードの有効期限切れを顧客に通知するという簡単なものもあれ
ば、自動車販売を目的とするマルチチャネルマーケティングキャンペーンといった複
雑なプロジェクトの一環である場合もあります。
42
第 4 章 ExactTarget の概要
内容は千差万別ですが、人との接点 (タッチポイント) になるという点は共通してま
す。人とは、つまり顧客であり、既存顧客の場合も見込み顧客の場合もあります。
メールやメッセージ、通知のどれもが、顧客とのタッチポイント、つまり顧客や見込
み客に影響を与える機会になると考えられます。
残念ながら、新しいシステムを急いで導入したり、時間を節約するために既存のイン
フラストラクチャを使用したりすれば、往々にしてこうした機会が失われます。さら
に、慎重に行わないと顧客や見込み客に悪影響を与えることにもなりかねません。
ExactTarget Marketing Cloud はマーケティング担当者が顧客タッチポイントを最大限に活
用することを支援します。このセクションでは、開発者の視点から各顧客タッチポイ
ントの効果を最大化するための重要事項について説明します。許可、パーソナライ
ズ、および各インタラクションの価値の最大化がこれらの重要事項の中心になりま
す。
関連性によるエンゲージメントの向上
顧客は、あらゆる種類のメッセージ (受信箱のメール、郵便受けの郵便物、高速道路
の広告板、モバイルデバイスの SMS や転送メッセージ、ソーシャルネットワークの広
告、ツイートや Facebook の友達リクエストなど) を大量に受け取っています。マーケ
ティング担当者は、これらのメッセージの関連性を高めて注目させないと効果がない
ことを把握しています。
43
第 4 章 ExactTarget の概要
的を絞った関連性の高いコミュニケーションを行うことは、マーケティング担当者に
とっての課題であると同時に、技術的な問題でもあります。マーケティングキャン
ペーンを大きく成功させるには、複数のデータソースからのデータを、厳密に分類し
た対象者に結び付け、複数のチャネルで洗練されたインテグレーションを行うことが
必要です。適切なメッセージを、適切な瞬間に提供する必要があります。このような
ことから、マーケティング担当者は目標を達成するために常に技術的支援を必要とし
ています。つまりこれは、開発者がマーケティング担当者と共に刷新に取り組む機会
でもあります。
データによる関連性の向上
マーケティング担当者が関連性の高いコミュニケーションを実現できるように、
ExactTarget Marketing Cloud は、柔軟なデータモデルと複数のインテグレーション手法を
通じて、大量のデータを複数のシステムで同期することを可能にします。このような
複数のソースからのデータを、顧客とコミュニケーションを行うときに AMPscript (メッ
セージング用の Marketing Cloud スクリプト言語) で使用し、顧客ごとに異なるメッセー
ジを作成することができます。たとえば、郵便番号を都市名に対応付けるデータ拡張
(データ拡張についての詳細は後で説明します) を作成し、次の AMPscript を介して、そ
の対応付けをコミュニケーションで動的に使用できます。
%%=Lookup("PostalCode","City","PostalCode",postalcode)=%%
あらゆるイベントで有意義なものを作る
イベント駆動型アーキテクチャは、リアルタイムシステムおよびアプリケーションの
拡張に不可欠です。モノのインターネットの時代に入っている現在において、これは
特に重要になります。各イベントは、生成元 (サーバ、Web ブラウザまたはモバイル
アプリケーション) に関係なく、顧客とやり取りする機会となります。また、そのイ
ベントに対する顧客の反応から顧客を分析することもできます。分析で得られた情報
は、今後、より有意義な対話をより適切なタイミングで行うために使用できます。
マーケティング担当者は、Marketing Cloud と、顧客との対話から得た詳しい情報を使用
してどのようなことができるでしょうか。「お問い合わせ」のような確認を行う顧客
イベントには、Marketing Cloud から特定のメッセージが特定のチャネルでそのまますぐ
に配信される場合もあります。一方、「購入」イベントなどの顧客イベントは Marketing
Cloud の Journey Builder エンジンに渡すことが必要になる場合もあります。これにより、
44
第 4 章 ExactTarget の概要
マーケティング担当者はイベントの価値を判断し、どのようなメッセージを配信して
応答するかを決定できます。
たとえば、映画レンタルシステムでは、顧客に領収書を送信するときに、映画のレ
ビューを依頼したり、別の映画のレンタルを促す特典を提示したりすることが考えら
れます。ExactTarget Fuel を使用して、顧客が映画をレンタルしたことを Marketing Cloud
インタラクションエンジンに通知すれば、システム内の他の多数のイベントや待機状
態を開始することができます。これらはすべて、その顧客の行動を望ましい次のス
テップに誘導するように設計されています。これがテクノロジとマーケティングのコ
ラボレーションです。このコラボレーションにより、顧客のプライバシーを尊重しな
がら、組織と顧客との関係の価値を高めるために緻密に作成された一連のイベントを
成功させることができます。
権限の重要性
顧客タッチポイントの管理方法に注意を払わないと、メールは迷惑な営業メール (ス
パム) としてみなされる可能性があります。
米国では CAN-SPAM 法が 2003 年に成立しました。これは、すべてのメールに配信停止
のメカニズムを追加することを義務付け、顧客からの送信停止要求に 10 日以内に応じ
ることを送信者に求めるものです。その他の多くの国でも、消費者を保護するために
同様の法律が実施されています。
45
第 4 章 ExactTarget の概要
CAN-SPAM では、営業メール (商品やサービスの広告またはプロモーション用のメール)
と 取引メール (イベントの結果として送信されるメール、または特定の取引に関する
情報が記載されたメール (パスワードリセットメールや購入確認メールなど)) が区別さ
れています。
企業が犯しやすいミスは、長年蓄積してきたメールアドレスまたは購入したメールア
ドレスのリストに営業メールを送信することです。そのリストが古い場合や、そのリ
ストの登録者の多くが自分にとって意味がないことを理由にメッセージをスパムとし
てフラグ設定している場合、その送信元 IP アドレスに対して否定的な評判が立ち、今
後のメール送信が失敗に終わる可能性があります。
顧客タッチポイントをうまく管理するには、許可を得ることが重要になります。
ExactTarget Marketing Cloud では、顧客に関連付けられたコミュニケーション設定 (特定の
コミュニケーションを許可または拒否しているかどうかなど) を保持し、メッセージ
の送信を営業または取引として指定できるようにすることで複雑な許可を管理できま
す。送信種別が営業である場合、ExactTarget はメールの本文内に送信停止リンクがあ
るかどうかを確認し、CAN-SPAM で求められているように、登録者が今後のコミュニ
ケーションを許可または拒否できるようにします。
顧客のためのテクノロジ
Marketing Cloud を使用してテクノロジとマーケティングを融合させる場合、顧客のため
の刷新と、顧客と企業/組織との関係性に常に焦点を当てます。ExactTarget Marketing Cloud
により、開発者は、顧客獲得および顧客維持に不可欠な方法を刷新したり、同じこと
を行う他のユーザを支援するシステムを構築したりできます。
ExactTarget Fuel で公開されるテクノロジと Marketing Cloud アプリケーションを組み合わ
せることで、開発者は個々の顧客レベルでの刷新を実行して、組織の価値を高めるこ
とができます。提供されているテクノロジは顧客に到達することを可能にします。そ
して、マーケティング担当者はこのテクノロジを利用できます。Fuel がビジネスの発
展と革新のためのパイプ役を果たします。
リソース
次のリソースから ExactTarget の詳細を入手できます。
• Code@ExactTarget 開発者コミュニティ: https://code.exacttarget.com
• Code@ExactTarget App Center: https://code.exacttarget.com/appcenter
46
第 4 章 ExactTarget の概要
• Fuel API: https://code.exacttarget.com/api
• Fuel SDK: https://code.exacttarget.com/sdks
• Fuel UX: https://code.exacttarget.com/fuelux
47
Force.com
第5章
認証
Force.com API では、認証を使用して Salesforce ユーザ情報にセキュアにアクセスします。
Force.com API を使用してユーザデータにアクセスする前に、OAuth を使用して適正な
ユーザであることを認証します。認証が成功すると、認証された Force.com API コール
の実行に使用するアクセストークンが提供されます。
OAuth を使用して認証するには、次の手順を実行する必要があります。
• Salesforce でリモートアクセスアプリケーション定義を設定します。
• 使用する正確な OAuth エンドポイントを決定します。
• 複数の異なる OAuth 2.0 認証フローのいずれかを介してユーザを認証します。OAuth
認証フローには、アプリケーションと Salesforce の間の認証プロセスを調整するた
めに使用する一連の手順が定義されています。次のような OAuth フローがサポート
されます。
– Web サーバフロー。サーバがセキュアにコンシューマの秘密を保護できます。
– ユーザエージェントフロー。コンシューマの秘密をセキュアに保存できないア
プリケーションによって使用されます。
– ユーザ名パスワードフロー。アプリケーションがユーザログイン情報に直接ア
クセスします。
接続アプリケーションの定義
OAuth を使用して認証を行う場合、Salesforce組織に対するアプリケーションの OAuth 設
定を定義する接続アプリケーションを作成する必要があります。
Salesforce での認証が必要な外部アプリケーションを開発する場合、Salesforce にこの新
規認証エントリポイントの情報を伝えるSalesforce内の新規接続アプリケーションとし
て定義する必要があります。
新規接続アプリケーションを作成するには、次の手順を実行します。
49
第 5 章 認証
1. [設定] から、[作成] > [アプリケーション] をクリックし、[新規] をクリックして
接続アプリケーションの定義を開始します。
2. アプリケーションの名前を入力します。
3. 取引先責任者のメール情報と、アプリケーションに応じたその他の情報を入力
します。
4. [OAuth 設定の有効化] を選択します。
5. [コールバック URL]を入力します。使用する OAuth フローに応じて、これは通
常、認証が成功した後にユーザのブラウザがリダイレクトされる URL になりま
す。この URL は一部の OAuth フローでアクセストークンを渡すために使用され
るため、URL はセキュア HTTP (HTTPS) またはカスタム URI スキームを使用する必
要があります。
6. サポートされているすべての OAuth 範囲を[選択した OAuth 範囲]に追加します。
これらの範囲とは、接続アプリケーションを実行するユーザによって付与され
る権限を示します。
7. [情報 URL] の URL を入力します。ユーザがこの URL にアクセスすると、アプリ
ケーションの詳細を参照できます。
8. [保存]をクリックします。[コンシューマ鍵] が作成され、表示されます。また、
[コンシューマの秘密] が作成されます (表示するにはリンクをクリックします)。
接続アプリケーションを定義したら、コンシューマ鍵とコンシューマの秘密を使用し
てアプリケーションを認証します。必要な認証種別の接続アプリケーションを作成す
る具体的な手順は、Salesforce オンラインヘルプの「接続アプリケーションの作成」を
参照してください。
OAuth エンドポイントについて
OAuth エンドポイントとは、Salesforce に対する OAuth 認証要求を行うために使用する
URL です。
アプリケーションで認証要求を発行する場合、正確な Salesforce OAuth エンドポイント
を使用する必要があります。主要な OAuth エンドポイントは次のとおりです。
• 認証: https://login.salesforce.com/services/oauth2/authorize
• トークン要求: https://login.salesforce.com/services/oauth2/token
50
第 5 章 認証
• OAuth トークンの取り消し:
https://login.salesforce.com/services/oauth2/revoke
すべてのエンドポイントでセキュア HTTP (HTTPS) が必要です。各 OAuth フローには、使
用する必要があるエンドポイントと指定する必要がある要求データが定義されていま
す。
Sandbox 組織で認証を検証する場合、上記に挙げたすべての OAuth エンドポイントで
「login.salesforce.com」の代わりに「test.salesforce.com」を使用してください。
Web サーバ OAuth 認証フローについて
安全なサーバでホストされているアプリケーションでは、Web サーバ認証フローを使
用します。Web サーバフローにおける重要な点は、サーバがコンシューマの秘密を保
護できる必要があります。また、フロー内の code challenge および code verifier の値を使
用して、認証コードの傍受を防ぐこともできます。
このフローでは、クライアントアプリケーションは、ユーザを認証してアプリケー
ションに認証コードを送信する他の Web サーバまたはリソースにユーザをリダイレク
トするように認証サーバに要求します。アプリケーションは認証コードを使用してア
クセストークンを要求します。このフローの手順は、次のとおりです。
51
第 5 章 認証
1. アプリケーションはユーザを適切な Salesforce 認証エンドポイント
(https://login.salesforce.com/services/oauth2/authorize など) に
リダイレクトします。次のパラメータは必須です。
パラメータ
説明
response_type
この認証フローの場合、code にする
必要があります。
52
第 5 章 認証
パラメータ
説明
client_id
接続アプリケーション定義の [コン
シューマ鍵]。
redirect_uri
接続アプリケーション定義の [コール
バック URL]。
次のパラメータは省略可能です。
パラメータ
説明
code_challenge
トークン要求で code_verifier 値の
SHA256 ハッシュ値を指定して、認証
コードの傍受攻撃を防ぐのに役立てま
す。ハッシュ値は、
https://tools.ietf.org/html/rfc4648#section-5
の定義に従って base64url エンコードす
る必要があります。
• 認証要求で code_challenge 値が
指定され、トークン要求で
code_verifier 値が指定されて
いる場合、Salesforce により
code_challenge が
code_verifier と比較されます。
code_challenge が無効であるか
一致しない場合、ログインが
invalid_request エラーコード
で失敗します。
• 認証要求で code_challenge 値が
指定されていても、トークン要求
で code_verifier 値が指定され
ていない場合、ログインが
invalid_grant エラーコードで
失敗します。
53
第 5 章 認証
パラメータ
説明
メモ: 値を base64url エンコードす
るのは 1 回のみです。
display
ログインページの表示の種類を変更し
ます。有効な値は、次のとおりです。
• page — 全画面のページ認証。こ
れは、値が指定されていない場合
のデフォルト値です。
• popup — 最新の Web ブラウザの
ポップアップウィンドウ用に最適
化されたコンパクトなダイアログ。
• touch — Android や iPhone など、最
新のスマートフォン用に設計され
たモバイル用に最適化されたダイ
アログ。
• mobile — BlackBerry OS 5 など、タッ
チスクリーンをサポートしていな
いスマートフォン用に設計された、
モバイル用に最適化されたダイア
ログ。
immediate
ログインと承認についてユーザにプロ
ンプトメッセージを表示するかどうか
を決定します。値は、true か false
のいずれかです。デフォルトは false
です。
• true に設定され、ユーザが現在ロ
グインしており、以前にこのアプ
リケーションを承認している場合、
承認ステップはスキップされます。
• true に設定され、ユーザがログイ
ンしていないか、これまでこのア
プリケーションを承認したことが
54
第 5 章 認証
パラメータ
説明
ない場合、セッションはただちに
エラーコード
immediate_unsuccessful で終
了します。
ログインページにユーザ名を自動入力
するための、有効なユーザ名の値を指
定します。たとえば、
login_hint
[email protected]
です。ユーザのブラウザにすでに有効
なセッションがある場合は、
login_hint パラメータの影響はな
く、有効なユーザセッションが継続さ
れます。
nonce
応答で返される値を指定します。「リ
プレイ」攻撃の検出に役立ちます。
ユーザ ID トークンを取得する場合の
openid 範囲に使用できます (省略可能)。
prompt
認証サーバがユーザに再認証および再
承認を求める方法を指定します。この
パラメータは省略可能です。Salesforce
でサポートされる値は、次のとおりで
す。
• login — 認証サーバがユーザに再
認証を求める必要があり、ユーザ
に強制的に再ログインさせます。
• consent — クライアントに情報を
戻す前に、認証サーバがユーザに
再認証を求める必要があります。
ユーザにログインおよび再認証の両方
を求めるには、スペースで区切られた
55
第 5 章 認証
パラメータ
説明
両方の値を渡すことが有効です。以下
に例を示します。
?prompt=login%20consent
scope
アプリケーションがアクセスできる
データを指定します。詳細は、オンラ
インヘルプの「範囲パラメータの値」
を参照してください。
state
承認後にコールバック URL で返され
る、追加の URL 符号化された状態デー
タを指定します。
認証 URL の例は、次のようになります。
https://login.salesforce.com/services/oauth2/authorize?response_type=code
&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3X
HrXDiCQjK1mdgAvhCscA9GE&redirect_uri=https%3A%2F%2Fwww.mysite.com%2F
code_callback.jsp&state=mystate
2. ユーザが自分のログイン情報で Salesforce にログインします。ユーザは認証エン
ドポイントを直接操作するため、アプリケーションがユーザのログイン情報を
認識することはありません。ログインに成功したら、ユーザはアプリケーショ
ンを認証するように要求されます。ユーザがすでにアプリケーションを認証し
ている場合、このステップはスキップされます。
3. クライアントアプリケーションが認証されたことが Salesforce で確認されると、
エンドユーザの Web ブラウザは、redirect_uri パラメータで指定されたコー
ルバック URL にリダイレクトされます。Salesforce は、認証情報を次の値でリダ
イレクト URL に付加します。
56
第 5 章 認証
パラメータ
説明
code
コンシューマがアクセストークンと更
新トークンを取得するために使用する
必要がある認証コード。
state
最初の要求の一部として渡される状態
値 (該当する場合のみ)。
認証情報が付属するコールバック URL の例は、次のようになります。
https://www.mysite.com/authcode_callback?code=aWekysIEeqM9PiT
hEfm0Cnr6MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w%3D%3D
4. アプリケーションは認証コードを抽出して、これをアクセストークン要求に含
めて Salesforce に渡す必要があります。この要求は、適切な Salesforce トークン要
求エンドポイント
(https://login.salesforce.com/services/oauth2/token など) に対し
て送信される POST 要求です。次のパラメータは必須です。
パラメータ
説明
grant_type
このフローの値は
authorization_code である必要が
あります。
client_id
接続アプリケーション定義の [コン
シューマ鍵]。
client_secret
接続アプリケーション定義の [コン
シューマの秘密]。
redirect_uri
接続アプリケーション定義の [コール
バック URL]。
code
コンシューマがアクセストークンと更
新トークンを取得するために使用する
必要がある認証コード。
57
第 5 章 認証
次のパラメータは省略可能です。
パラメータ
説明
client_assertion
client_secret を渡す代わりに、
client_assertion および
client_assertion_type を提供で
きます。client_secret パラメータ
が指定されていない場合、Salesforce に
よって自動的に client_assertion
および client_assertion_type が
チェックされます。
client_assertion の値は、OAuth コ
ンシューマがアップロードした証明書
に関連付けられている非公開鍵で署名
された一般的な JWT ベアラートークン
である必要があります。現在、RS256
アルゴリズムのみがサポートされてい
ます。client_assertion の使用に
ついての詳細は、private_key_jwt クライ
アント認証メソッドの「OpenID Connect
の仕様」を参照してください。
client_assertion_type
client_assertion パラメータを使
用するときにこの値を指定します。
client_assertion_type の値は、
urn:ietf:params:oauth:client-assertion-type:jwt-bearer
でなければなりません。
code_verifier
高エントロピの 128 バイトのランダム
なデータを指定して値の推測を困難に
することで、認証コードの傍受攻撃を
防ぐのに役立てます。この値も、
https://tools.ietf.org/html/rfc4648#section-5
の定義に従って base64url エンコードす
る必要があります。
58
第 5 章 認証
パラメータ
説明
• トークン要求で code_verifier
値が指定され、認証要求で
code_challenge 値が指定されて
いる場合、Salesforce により
code_verifier が
code_challenge と比較されま
す。code_verifier が無効である
か一致しない場合、ログインが
invalid_grant エラーコードで
失敗します。
• トークン要求で code_verifier
値が指定されていても、認証要求
で code_challenge 値が指定され
ていない場合、ログインが
invalid_grant エラーコードで
失敗します。
メモ: 値を base64url エンコードす
るのは 1 回のみです。
期待される戻り形式。デフォルトは
json です。値は次のとおりです。
format
• urlencoded
• json
• xml
返される形式は、要求のヘッダーに次
のいずれかを使用して指定することも
できます。
• Accept:
application/x-www-form-urlencoded
• Accept: application/json
• Accept: application/xml
59
第 5 章 認証
アクセストークン POST 要求の例は、次のようになります。
POST /services/oauth2/token HTTP/1.1
Host: login.salesforce.com
grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&client_id=3MVG9lKcPoNI
NVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCs
cA9GE&client_secret=1955279925675241571&
redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jsp
5. この要求が成功した場合、サーバは次の内容を持つレスポンスボディを返しま
す。
パラメータ
説明
access_token
アプリケーションが要求を行うために
使用するセッション ID として機能する
アクセストークン。このトークンは、
ユーザログイン情報と同様に保護する
必要があります。
refresh_token
新しいアクセストークンを取得するた
めに将来使用できるトークン。
警告: この値は秘密です。ユーザ
のパスワードなどと同様に処理
し、適切な手段で保護する必要
があります。
instance_url
API コールの送信先となる Salesforce イ
ンスタンスを示します。
id
ユーザ、およびユーザの詳細に関する
クエリの両方を識別するために使用で
きる ID URL。エンドユーザに関する詳
60
第 5 章 認証
パラメータ
説明
細な情報を取得するための HTTP 要求
で使用できます。
issued_at
署名が作成された日時。UNIX エポック
(1970 年 1 月 1 日 00:00:00 UTC) からの秒
数として表されます。
signature
連結 ID と issued_at 値を含むコン
シューマの非公開鍵で署名されている
Base64 符号化された HMAC-SHA256 署
名。この signature は、ID URL がサー
バから送信された後に変更されていな
いことを確認するために使用できま
す。
JSON レスポンスボディの例は、次のようになります。
{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448101416",
"refresh_token":"5Aep8614iLM.Dq661ePDmPEgaAW9Oh_L3JKkDpB4xReb54_
pZebnUG0h6Sb4KUVDpNtWEofWM39yg==",
"instance_url":"https://na1.salesforce.com",
"signature":"CMJ4l+CCaPQiKjoOEwEig9H4wqhpuLSk4J2urAe+fVg=",
"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0R
NBaT1cyWk7TrqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4"}
6. アプリケーションは、提供されたアクセストークンと更新トークンを使用して
保護されたユーザデータにアクセスします。
61
第 5 章 認証
ユーザエージェント OAuth 認証フローについて
ユーザエージェント認証フローは、ユーザのデバイスにあるクライアントアプリケー
ション (コンシューマ) で使用されます。これは、JavaScript などのスクリプト言語を使
用するブラウザ内で、または携帯機器またはデスクトップアプリケーションから実装
することができます。これらのコンシューマは顧客の秘密の機密を保持することがで
きません。
このフローでは、クライアントアプリケーションは、アクセストークンを抽出してア
プリケーションに戻すことができる他の Web サーバまたはリソースにユーザをリダイ
レクトするように認証サーバに要求します。このフローの手順は、次のとおりです。
62
第 5 章 認証
1. アプリケーションはユーザを適切な Salesforce 認証エンドポイント
(https://login.salesforce.com/services/oauth2/authorize など) に
リダイレクトします。次のパラメータは必須です。
パラメータ
説明
response_type
この認証フローの場合、必ず token
にする
client_id
接続アプリケーション定義の [コン
シューマ鍵]。
redirect_uri
接続アプリケーション定義の [コール
バック URL]。
次のパラメータは省略可能です。
パラメータ
説明
display
ログインページの表示の種類を変更し
ます。有効な値は、次のとおりです。
• page — 全画面のページ認証。こ
れは、値が指定されていない場合
のデフォルト値です。
• popup — 最新の Web ブラウザの
ポップアップウィンドウ用に最適
化されたコンパクトなダイアログ。
• touch — Android や iPhone など、最
新のスマートフォン用に設計され
たモバイル用に最適化されたダイ
アログ。
• mobile — BlackBerry OS 5 など、タッ
チスクリーンをサポートしていな
いスマートフォン用に設計された、
モバイル用に最適化されたダイア
ログ。
63
第 5 章 認証
パラメータ
説明
scope
アプリケーションがアクセスできる
データを指定します。詳細は、オンラ
インヘルプの「範囲パラメータの値」
を参照してください。
state
承認後にコールバック URL で返され
る、追加の URL 符号化された状態デー
タを指定します。
認証 URL の例は、次のようになります。
https://login.salesforce.com/services/oauth2/authorize?response_type=token&
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLJbP_pqwoJYyuisjQhr_LLurNDv7AgQvDTZwCoZuD
ZrXcPCmBv4o.8ds.5iE&redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fuser_callback.jsp&
state=mystate
2. ユーザが自分のログイン情報で Salesforce にログインします。ユーザは認証エン
ドポイントを直接操作するため、アプリケーションがユーザのログイン情報を
認識することはありません。
3. 認証されると、認証エンドポイントはユーザをリダイレクト URL にリダイレク
トします。この URL は、アプリケーション用に作成されたリモートアクセスア
プリケーションに定義されています。Salesforce は、アクセストークン情報を次
の値でリダイレクト URL に付加します。
パラメータ
説明
access_token
アプリケーションが要求を行うために
使用するセッション ID として機能する
アクセストークン。このトークンは、
ユーザログイン情報と同様に保護する
必要があります。
expires_in
アクセストークンが有効な時間 (秒)。
64
第 5 章 認証
パラメータ
説明
refresh_token
新しいアクセストークンを取得するた
めに将来使用できるトークン。
警告: この値は秘密です。ユーザ
のパスワードなどと同様に処理
し、適切な手段で保護する必要
があります。
更新トークンが返されるのは、リダイ
レクト URI が
https://login.salesforce.com/services/oauth2/success
であるか、HTTPS 以外のカスタムプロ
トコルで使用されている場合のみで
す。
state
最初の要求の一部として渡される状態
値 (該当する場合のみ)。
instance_url
API コールの送信先となる Salesforce イ
ンスタンスを示します。
id
ユーザ、およびユーザの詳細に関する
クエリの両方を識別するために使用で
きる ID URL。エンドユーザに関する詳
細な情報を取得するための HTTP 要求
で使用できます。
issued_at
署名が作成された日時。UNIX エポック
(1970 年 1 月 1 日 00:00:00 UTC) からの秒
数として表されます。
signature
連結 ID と issued_at 値を含むコン
シューマの非公開鍵で署名されている
Base64 符号化された HMAC-SHA256 署
名。この signature は、ID URL がサー
バから送信された後に変更されていな
いことを確認するために使用できま
す。
65
第 5 章 認証
アクセス情報がハッシュ記号 (#) の後に付加されたコールバック URL の例は、次
のようになります。
https://www.mysite.com/user_callback.jsp#access_token=00Dx0000000BV7z%21AR8
AQBM8J_xr9kLqmZIRyQxZgLcM4HVi41aGtW0qW3JCzf5xdTGGGSoVim8FfJkZEqxbjaFbberKGk
8v8AnYrvChG4qJbQo8&refresh_token=5Aep8614iLM.Dq661ePDmPEgaAW9Oh_L3JKkDpB4xR
eb54_pZfVti1dPEk8aimw4Hr9ne7VXXVSIQ%3D%3D&expires_in=7200&state=mystate
4. アプリケーションは、提供されたアクセストークンと更新トークンを使用して
保護されたユーザデータにアクセスします。
ユーザエージェント OAuth フローを使用するときの考慮事項は、次のとおりです。
• アクセストークンは符号化され、リダイレクト URI になっているため、エンドユー
ザや、コンピュータまたはデバイス上にある他のアプリケーションに公開できま
す。JavaScript を使用して認証する場合、window.location.replace(); をコー
ルし、ブラウザの履歴からコールバックを削除します。
ユーザ名パスワード OAuth 認証フローについて
コンシューマにすでにユーザの認証情報がある場合、ユーザ名パスワード認証フロー
を使用して認証できます。
このフローでは、次の手順のようにアプリケーションがユーザのログイン情報を使用
してアクセストークンを要求します。
警告: この OAuth 認証フローでは、ユーザのログイン情報をやり取りする必要が
あります。この認証フローは、必要な場合にのみ使用してください。更新トーク
ンは発行されません。
66
第 5 章 認証
1. コンシューマはユーザのユーザ名とパスワードを使用してアクセストークンを
要求します。これを行うには、適切な Salesforce トークン要求エンドポイント
(https://login.salesforce.com/services/oauth2/token など) に対し
て帯域外 POST 要求を行います。次の要求項目は必須です。
パラメータ
説明
grant_type
この認証フローの場合、password に
する必要があります。
client_id
接続アプリケーション定義の [コン
シューマ鍵]。
67
第 5 章 認証
パラメータ
説明
client_secret
接続アプリケーション定義の [コン
シューマの秘密]。
username
エンドユーザのユーザ名。
password
エンドユーザのパスワード。
メモ: ユーザのセキュリティトー
クンをユーザのパスワードに付
加する必要があります。セキュ
リティトークンは、Salesforce で
自動生成されたキーです。たと
えば、ユーザのパスワードが
mypassword で、セキュリティトー
クンが XXXXXXXXXX の場合は、こ
のパラメータには、値
mypasswordXXXXXXXXXX を指定す
る必要があります。セキュリ
ティトークンの詳細は、オンラ
インヘルプの「セキュリティ
トークンのリセット」を参照し
てください。
リクエストボディの例は、次のようになります。
grant_type=password&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82Hn
FVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&client_secret=
1955279925675241571&username=testuser%40salesforce.com&password=mypassword123456
2. Salesforce はユーザログイン情報を検証し、成功したら、応答とアクセストーク
ンをアプリケーションに送信します。この応答には次の値が含まれます。
68
第 5 章 認証
パラメータ
説明
access_token
アプリケーションが要求を行うために
使用するセッション ID として機能する
アクセストークン。このトークンは、
ユーザログイン情報と同様に保護する
必要があります。
instance_url
API コールの送信先となる Salesforce イ
ンスタンスを示します。
id
ユーザ、およびユーザの詳細に関する
クエリの両方を識別するために使用で
きる ID URL。エンドユーザに関する詳
細な情報を取得するための HTTP 要求
で使用できます。
issued_at
署名が作成された日時。UNIX エポック
(1970 年 1 月 1 日 00:00:00 UTC) からの秒
数として表されます。
signature
連結 ID と issued_at 値を含むコン
シューマの非公開鍵で署名されている
Base64 符号化された HMAC-SHA256 署
名。この signature は、ID URL がサー
バから送信された後に変更されていな
いことを確認するために使用できま
す。
レスポンスボディの例は、次のようになります。
{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448832702","instance_url":"https://na1.salesforce.com",
"signature":"0CmxinZir53Yex7nE0TD+zMpvIWYGb/bdJh6XfOH6EQ=","access_token":
"00Dx0000000BV7z!AR8AQAxo9UfVkh8AlV0Gomt9Czx9LjHnSSpwBMmbRcgKFmxOtvxjTrKW1
69
第 5 章 認証
9ye6PE3Ds1eQz3z8jr3W7_VbWmEu4Q8TVGSTHxs"}
3. アプリケーションは、提供されたアクセストークンを使用して保護されたユー
ザデータにアクセスします。
ユーザエージェント OAuth フローを使用するときの考慮事項は、次のとおりです。
• このフローではユーザが Salesforce でログインするためにリダイレクトされること
はないため、ユーザは直接アプリケーションを認証できません。そのため、更新
トークンは使用できません。アプリケーションで更新トークンが必要な場合、Web
サーバまたはユーザエージェント OAuth フローの使用を検討してください。
OAuth 更新トークンプロセスについて
Web サーバ OAuth 認証フローとユーザエージェントフローはどちらも、新しいアクセ
ストークンの取得に使用可能な更新トークンを提供します。
アクセストークンは、Salesforce のセッションタイムアウトで指定された有効期間に制
限されています。アプリケーションが有効期限の切れたアクセストークンを使用する
と、「Session expired or invalid」エラーが返されます。アプリケーションが Web サーバま
たはユーザエージェント OAuth 認証フローを使用している場合、認証中に更新トーク
ンが提供され、新しいアクセストークンの取得に使用できる可能性があります。
クライアントアプリケーションが新しいアクセストークンを取得するには、次の要求
パラメータを指定して POST 要求をトークン要求エンドポイントに送信します。
パラメータ
説明
grant_type
値は refresh_token である必要があり
ます。
refresh_token
クライアントアプリケーションがすでに
受け取っている更新トークン。
client_id
接続アプリケーション定義の [コンシュー
マ鍵]。
70
第 5 章 認証
パラメータ
説明
client_secret
接続アプリケーション定義の [コンシュー
マの秘密]。このパラメータは省略可能で
す。
format
期待される戻り形式。デフォルトは、
json です。値は次のとおりです。
• urlencoded
• json
• xml
返される形式は、要求のヘッダーに次の
いずれかを使用して指定することもでき
ます。
• Accept:
application/x-www-form-urlencoded
• Accept: application/json
• Accept: application/xml
このパラメータは省略可能です。
更新トークン POST 要求の例は、次のようになります。
POST /services/oauth2/token HTTP/1.1
Host: https://login.salesforce.com/
grant_type=refresh_token&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0
QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&client_secret=1955279925675241571
&refresh_token=your token here
Salesforce は、更新トークン要求を検証した後、次のレスポンスボディパラメータを使
用してアプリケーションに応答を送信します。
71
第 5 章 認証
パラメータ
説明
access_token
アプリケーションが要求を行うために使
用するセッション ID として機能するアク
セストークン。このトークンは、ユーザ
ログイン情報と同様に保護する必要があ
ります。
instance_url
API コールの送信先となる Salesforce インス
タンスを示します。
id
ユーザ、およびユーザの詳細に関するク
エリの両方を識別するために使用できる
ID URL。エンドユーザに関する詳細な情報
を取得するための HTTP 要求で使用できま
す。
issued_at
署名が作成された日時。UNIX エポック
(1970 年 1 月 1 日 00:00:00 UTC) からの秒数と
して表されます。
signature
連結 ID と issued_at 値を含むコンシュー
マの非公開鍵で署名されている Base64 符
号化された HMAC-SHA256 署名。この
signature は、ID URL がサーバから送信
された後に変更されていないことを確認
するために使用できます。
JSON レスポンスボディの例は、次のようになります。
{
"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448384422","instance_url":"https://na1.salesforce.com",
"signature":"SSSbLO/gBhmmyNUvN18ODBDFYHzakxOMgqYtu+hDPsc=",
"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNBaT1cyWk7T
72
第 5 章 認証
rqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4"}
更新トークン OAuth プロセスを使用するときの考慮事項は、次のとおりです。
• アクセストークンのセッションタイムアウトをSalesforceで設定するには、[設定] か
ら [セキュリティのコントロール] > [セッションの設定] をクリックします。
• アプリケーションがユーザ名パスワード OAuth 認証フローを使用する場合、このフ
ローではユーザはアプリケーションを認証できないため、更新トークンは発行さ
れません。アクセストークンの有効期限が切れた場合、ユーザ名パスワード OAuth
フローを使用するアプリケーションはユーザを再認証する必要があります。
その他のリソースを見つける
次のリソースは、Salesforce で OAuth を使用するときの関連情報を説明しています。
• Authenticating Apps with OAuth (OAuth によるアプリケーションの認証)
• Digging Deeper into OAuth on Force.com (Force.com の OAuth の詳細)
• Using OAuth to Authorize External Applications (OAuth を使用した外部アプリケーションの
認証)
OAuth を実装するサードパーティクライアントライブラリとして、次のようなリソー
スを必要に応じて参考にしてください。
• Ruby on Rails: OmniAuth
• Java: Apache Amber
• その他の OAuth クライアントライブラリ: OAuth.net
73
第6章
SOAP API
SOAP API を使用すると、Salesforce で管理されるレコードを作成、取得、更新、削除で
きるForce.comアプリケーションを、Web サービスをサポートする任意の開発環境を使
用して統合できます。
SOAP API を使用するケース
SOAP API では、Salesforce を操作するための強力で便利な使いやすい SOAP ベースの Web
サービスインターフェースを提供します。SOAP API を使用して、レコードを作成、取
得、更新、または削除できます。また、SOAP API を使用して、検索の実行などを行う
ことができます。SOAP APIは、Web サービスをサポートしている言語で使用できます。
たとえば、SOAP API を使用して Salesforce を組織の ERP や会計システムに統合し、リア
ルタイムの販売情報やサポート情報を会社のポータルに配信し、重要なビジネスシス
テムに顧客情報を投入します。
サポート対象のエディションとプラットフォーム
SOAP API を使用するには、組織で Enterprise Edition、Performance Edition、Unlimited Edition、
または Developer Edition を使用する必要があります。既存の Salesforce のお客様が Enterprise
Edition、Unlimited Edition、または Performance Edition にアップグレードする場合は、担当
者にご連絡ください。
クイックスタート
ここでは、ご使用の開発環境でサンプルアプリケーションを作成する手順について説
明します。
75
第 6 章 SOAP API
メモ: インテグレーションまたはその他のクライアントアプリケーションを作成
する前に、次のことを実行してください。
• 製品マニュアルに従って、開発プラットフォームをインストールする。
• このクイックスタートを開始する前に、すべての手順に目を通す。用語およ
びコンセプトについて理解するために、このマニュアルの残りの部分を確認
する必要もあります。
ベストプラクティス
この章では、インテグレーションアプリケーションをはじめとするアプリケーション
を開発する前に考慮すべき、データ管理、使用制限、通信などの課題について説明し
ます。
ユーザ権限
クライアントアプリケーションが SOAP API に接続するとき、最初にログインする必要
があります。クライアントアプリケーションは、ログインユーザの権限および共有設
定に基づいて動作します。
組織のSalesforce管理者は、プロファイルおよび権限セットを設定し、ユーザをそれら
に割り当てることによって、さまざまな機能やビューの使用を制御します。API にア
クセスするには (コールを発行してコール結果を受信するには)、ユーザに「API 対応」
権限が割り当てられている必要があります。クライアントアプリケーションは、ログ
インユーザの権限を介してアクセス権限を付与されるこれらのオブジェクトおよび項
目のみをクエリしたり更新したりできます。
共有ルールによってデータへのアクセスを許可されたユーザとしてのログインでは、
API はアクセスを確認する追加のクエリを発行する必要があります。それを避けるに
は、「すべてのデータの編集」権限を持つユーザとしてログインします。
API 利用状況の監視
組織で生成された SOAP API 要求の数を監視するには、次の 2 つの方法があります。
76
第 6 章 SOAP API
• すべてのユーザが 24 時間以内に送信された API 要求の数を確認できます。この情
報を参照するには、[設定] から、[組織プロファイル] > [組織情報] をクリックしま
す。右の列の [API 要求数 (この 24 時間以内)] を参照します。
• ユーザが「すべてのデータの編集」権限を持つ場合、7 日以内に送信された API 要
求のレポートを参照できます。情報を参照するには、[レポート] タブをクリック
し、[管理レポート] セクションにスクロールして [過去 7 日間の API 使用状況] リン
クをクリックします。[集計情報:]ドロップダウンリストにある任意の項目でレポー
トを並び替えることができます。
クエリの制限
ユーザが同時に実行できるクエリの数は制限されています。ユーザは一度に最大 10 個
のクエリカーソルを開くことができます。同じユーザとしてログインしているクライ
アントアプリケーションが、新しい QueryLocator カーソルを開こうとしたときに、
10 個のカーソルがすでに開かれていると、そのうち最も古いカーソルが解放されま
す。クライアントアプリケーションがリリースされたクエリカーソルを開こうとする
と、エラーになります。
複数のクライアントアプリケーションが、同じ username 引数を使用してログインで
きます。ただし、クエリ制限によってエラーになるリスクが高くなります。
複数のクライアントアプリケーションが同じユーザを使用してログインした場合、そ
のアプリケーションすべてで同じセッションが共有されます。いずれかのクライアン
トアプリケーションが logout() をコールすると、すべてのクライアントアプリケー
ションのセッションが無効になります。クライアントアプリケーションごとに異なる
ユーザを使用すると、こうした制限を回避しやすくなります。
API 要求の制限
最適なパフォーマンスを維持し、すべてのお客様が Force.com API を使用できるように
するために、Salesforce は次の 2 つの制限を設けることによって、トランザクションの
負荷を調整しています。
• 同時 API 要求数の制限
• API 要求数の合計に対する制限
コールが要求制限を超えると、エラーが返されます。
77
第 6 章 SOAP API
次の表は、20 秒以上の同時要求 (コール) 数について、さまざまな種類の組織に対する
制限を示しています。
組織種別
制限
Developer Edition
5
トライアルの組織
5
本番組織
25
Sandbox
25
次の表は、組織の 24 時間あたりの API 要求 (コール) 数の合計に関する制限について示
しています。
Salesforce のエディ
ション
ライセンスの種類ごとの API コー 最小
ル数
すべてのエディショ なし
ン: 指定の Apex 用の
APIテストコールに対
する
DebuggingHeader。API
バージョン 20 以降で
有効。
最大
1,000
1,000
Developer Edition
なし
15,000
15,000
• Enterprise Edition
• Salesforce: 1,000
15,000
1,000,000
• Professional Edition • Force.com App Subscription: 200
(APIアクセス有効) • Salesforce プラットフォーム:
1,000
• Force.com - One App: 200
メモ: 新規ユーザは、こ
のライセンスを使用で
きません。
78
第 6 章 SOAP API
Salesforce のエディ
ション
ライセンスの種類ごとの API コー 最小
ル数
最大
• パートナーコミュニティ: 200
• Gold Partner: 200
メモ: 新規ユーザは、こ
のライセンスを使用で
きません。
• Unlimited Edition
• Salesforce: 5,000
• Performance Edition
• Force.com App Subscription: 200
15,000
制限なし。
ただし、高
い数値を設
定すると、
システム負
荷などのそ
の他の制限
要因によっ
て、24 時間
すべての
コール割り
当てを使用
できなくな
る可能性が
高まりま
す。
なし
5,000,000
• Salesforce プラットフォーム:
5,000
• Force.com - One App: 200
メモ: 新規ユーザは、こ
のライセンスを使用で
きません。
• パートナーコミュニティ: 200
• Gold Partner: 200
メモ: 新規ユーザは、こ
のライセンスを使用で
きません。
Sandbox
なし
コール数の制限は、24 時間あたりに組織で行われた API コール数の集計に対して適用
されます。この制限は、ユーザごとに適用されるものではありません。組織がこの制
限を超過した場合、組織内のすべてのユーザが一時的にブロックされ、追加のコール
を行うことができなくなります。直近 24 時間の使用状況が制限値内に収まるまで、
コールはブロックされます。
79
第 6 章 SOAP API
Salesforce データベースサーバの複数インスタンス
Salesforce は数多くのデータベースサーバインスタンスを提供しています。通常組織は
地理的な地域ごとに分けられていますが、組織はあらゆるインスタンスに置かれる可
能性があります。
コンテンツタイプの要件
API バージョン 7.0 以降では、すべての要求には Content-Type: text/xml;
charset=utf-8 などの正しいコンテンツタイプの HTTP ヘッダーを含んでいなければ
なりません。バージョン 7.0 より前の API ではこの要件は適用されません。
圧縮
SOAP API は、HTTP 1.1 仕様で定義された標準を使用した要求と応答の圧縮をサポートし
ています。いくつかの SOAP/WSDL クライアントでは自動的にサポートされており、他
のクライアントへも手動で追加できます。クライアント別の詳細は、
https://developer.salesforce.com/page/Tools を参照してください。
クライアントが圧縮をサポートしていることを示すには、HTTP ヘッダー「Accept-Encoding:
gzip, deflate」または同様のヘッダーを含める必要があります。クライアントでこのヘッ
ダーが正しく指定されている場合、SOAP API は応答を圧縮します。レスポンスには、
「Content-Encoding: deflate」または「Content-Encoding: gzip」のいずれか適切な方が含まれ
ます。「Content-Encoding: deflate」または「gzip」をヘッダーに含めることで、あらゆる
要求を圧縮することができます。
HTTP 永続接続
ほとんどのクライアントでは、HTTP 1.1 の永続接続を使用し、複数の要求のソケット
接続を再利用したほうがパフォーマンスが向上します。永続接続は通常 SOAP/WSDL ク
ライアントが自動的に処理します。詳細は、次の HTTP 1.1 の仕様を参照してください。
http://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.1
80
第 6 章 SOAP API
HTTP のチャンク
HTTP 1.1 を使用しているクライアントは、チャンクレスポンスを受け取ることがあり
ます。チャンクは通常 SOAP/WSDL クライアントが自動的に処理します。
リソース
SOAP API に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• SOAP API 開発者ガイド
• SOAP API 開発者早見表
• Salesforce オブジェクトリファレンス
• API とインテグレーションに関するフォーラム
81
第7章
REST API
REST API は、Salesforce を操作するための REST ベースの API を提供します。REST API を使用
すると、Salesforce で管理されるレコードを作成、取得、更新、削除できる Force.com ア
プリケーションを、Web サービスをサポートする任意の開発環境を使用して作成でき
ます。
REST API を使用するケース
REST API では、Salesforce を操作するための強力で便利な使いやすい REST ベースの Web
サービスインターフェースを提供します。インテグレーションおよび開発が容易とい
う利点があり、モバイルアプリケーションや Web プロジェクトで使用するための技術
の選択としては最適です。ただし、処理するレコード件数が多い場合、REST 規則に基
づいており、大規模データセットの処理用に最適化されている Bulk API を使用するこ
とをお勧めします。
サポート対象のエディションとプラットフォーム
REST API を使用するには、組織で Enterprise Edition、Performance Edition、Unlimited Edition、
または Developer Edition を使用する必要があります。既存の Salesforce のお客様が Enterprise
Edition、Unlimited Edition、または Performance Edition にアップグレードする場合は、担当
者にご連絡ください。
クイックスタート
開発環境に REST サンプルアプリケーションを作成し、REST API の能力と柔軟性を確認
します。
83
第 7 章 REST API
前提条件
次の前提条件をすべて満たすことで、クイックスタートのサンプルの作成と使用が容
易になります。cURL および JavaScript Object Notation (JSON) に慣れていない場合は、ワー
クベンチを使用してデータを取得することもできます。
• 製品ドキュメントに従って、開発プラットフォームをインストールする。
• このクイックスタートで REST 要求の実行に使用するツールである cURL に習熟して
おく。他のツールを使用する場合は、コード例を変換できるようにそのツールに
十分慣れておく必要があります。
• このクイックスタートで使用する JSON に習熟しておく。JSON を使用しない場合
は、サンプルを JSON から読み換えられる程度に自分が使用する標準言語に習熟し
ている必要があります。
• アプリケーションサーバの SSL エンドポイントを有効にする。
• OAuth 2.0 に習熟しておく。OAuth 2.0 にはいくつかの設定が必要です。手順は説明し
ますが、基本的な概念とワークフローを理解しておくと役に立ちます。
• このクイックスタートを開始する前に、すべての手順に目を通す。このガイドの
他の部分を確認しておくと、用語や概念を把握できます。
ステップ 1: Salesforce Developer Edition 組織を取得する
まだ Force.com 開発者コミュニティのメンバーでない場合、
developer.salesforce.com/signup にアクセスし、Developer Edition 組織のサイン
アップの説明に従ってください。すでに Enterprise Edition、Unlimited Edition、または
Performance Edition を所有している場合でも、組織の使用中のデータを保護するために、
サンプルデータに対するソリューションの開発、ステージングおよびテストには
Developer Edition を使用します。これは、特に、(データをただ参照するだけのアプリ
ケーションに対し) データを挿入、更新または削除するアプリケーションの場合に該
当します。
Developer Edition 組織をすでに所有している場合は、「API の有効化」権限があることを
確認します。この権限はデフォルトで有効になっていますが、管理者によって変更さ
れている場合があります。詳細は、Salesforce ユーザインターフェースのヘルプを参照
してください。
84
第 7 章 REST API
ステップ 2: 認証を設定する
OAuth 2.0 を使用して、またはセッション ID を渡すことによって、認証を設定できま
す。
重要: 他のユーザのパスワードを処理している場合は、セッション ID は使用しな
いでください。
認証用の OAuth コンシューマ ID の取得を希望するパートナー様は Salesforce まで連絡し
てください。
OAuth 2.0 の設定
OAuth 2.0 の設定には、Salesforce 内と他の場所でのいくつかのステップを実行する必要
があります。ステップに不明な点がある場合は、「認証について」またはSalesforceオ
ンラインヘルプを参照してください。次の例では、Web サーバ OAuth フローを使用し
ます。
1. まだ新しい接続アプリケーションを作成していない場合は、Salesforceで、[設定]
から [作成] > [アプリケーション] をクリックし、[接続アプリケーション] で [新
規] をクリックして作成します。ここで指定する [コールバック URL] は、Web
アプリケーションのコールバック URL と同じです。Java を使用する場合、通常
はこれはサーブレットです。コールバック URL はセキュアである必要がありま
す。http:// は機能せず、https:// のみが機能します。開発環境では、コー
ルバック URL は https://localhost:8443/RestTest/oauth/_callback の
ような形になります。[保存] をクリックすると、[コンシューマ鍵] が作成され
て表示され、[コンシューマの秘密] が作成されます (リンクをクリックして表
示します)。
メモ: OAuth 2.0 仕様では、「consumer (コンシューマ)」ではなく「client (ク
ライアント)」という表現が使われます。Salesforce は OAuth 2.0 をサポート
します。
Salesforce のリモートアクセスアプリケーションで使用される用語と、この手順
の残りの部分にあるサンプルコードに含まれる値は次のように対応します。
• client_id は [コンシューマ鍵] に対応
• client_secret は [コンシューマの秘密] に対応
• redirect_uri は [コールバック URL] に対応
85
第 7 章 REST API
クライアントアプリケーションでは、ユーザを適切な Salesforce 認証エンドポイ
ントにリダイレクトします。ユーザのログインが成功すると、Salesforce は認証
コードでリダイレクト URI をコールします。次のステップでは、認証コードを
使用してアクセストークンを取得します。
2. Java またはその他のクライアントアプリケーションから、適切な Salesforce トー
クン要求エンドポイントに要求を行い、grant_type、client_id、
client_secret、および redirect_uri を渡します。redirect_uri は、
Salesforce がコールバック送信する先の URI です。
initParams = {
@WebInitParam(name = "clientId", value =
"3MVG9lKcPoNINVBJSoQsNCD.HHDdbugPsNXwwyFbgb47KWa_PTv"),
@WebInitParam(name = "clientSecret", value =
"5678471853609579508"),
@WebInitParam(name = "redirectUri", value =
"https://localhost:8443/RestTest/oauth/_callback"),
@WebInitParam(name = "environment", value =
"https://na1.salesforce.com/services/oauth2/token")
}
HttpClient httpclient = new HttpClient();
PostMethod post = new PostMethod(environment);
post.addParameter("code",code);
post.addParameter("grant_type","authorization_code");
86
第 7 章 REST API
/** For session ID instead of OAuth 2.0, use "grant_type",
"password" **/
post.addParameter("client_id",clientId);
post.addParameter("client_secret",clientSecret);
post.addParameter("redirect_uri",redirectUri);
client_id (または consumer key) の値と client_secret (または consumer
secret) が有効な場合、Salesforce はコールバックを、access_token. の値が
含まれる redirect_uri に指定された URI に送信します。
3. アクセストークンの値を Cookie として保存し、以降のすべての要求で使用しま
す。次に例を示します。
//exception handling removed for brevity...
//this is the post from step 2
httpclient.executeMethod(post);
String responseBody = post.getResponseBodyAsString();
String accessToken = null;
JSONObject json = null;
try {
json = new JSONObject(responseBody);
accessToken = json.getString("access_token");
issuedAt = json.getString("issued_at");
/** Use this to validate session
* instead of expiring on browser close.
87
第 7 章 REST API
*/
} catch (JSONException e) {
e.printStackTrace();
}
HttpServletResponse httpResponse =
(HttpServletResponse)response;
Cookie session = new Cookie(ACCESS_TOKEN, accessToken);
session.setMaxAge(-1); //cookie not persistent, destroyed
on browser exit
httpResponse.addCookie(session);
これで、認証は完了です。
4. 認証されると、各要求は、ヘッダーに access_token 値を渡す必要がありま
す。要求パラメータとして渡すことはできません。
HttpClient httpclient = new HttpClient();
GetMethod gm = new GetMethod(serviceUrl);
//set the token in the header
gm.setRequestHeader("Authorization", "Bearer "+accessToken);
//set the SOQL as a query param
NameValuePair[] params = new NameValuePair[1];
88
第 7 章 REST API
/**
* other option instead of query string, pass just the fields
you want back:
*
https://instance_name.salesforce.com/services/data/v20.0/sobjects/Account/
*
001D000000INjVe?fields=AccountNumber,BillingPostalCode
*/
params[0] = new NameValuePair("q","SELECT name, title FROM
Contact LIMIT 100");
gm.setQueryString(params);
httpclient.executeMethod(gm);
String responseBody = gm.getResponseBodyAsString();
//exception handling removed for brevity
JSONObject json = new JSONObject(responseBody);
JSONArray results = json.getJSONArray("records");
for(int i = 0; i < results.length(); i++)
response.getWriter().write(results.getJSONObject(i).getString("Name")+
",
89
第 7 章 REST API
"+results.getJSONObject(i).getString("Title")+"\n");
REST 要求にアクセストークンを提供する構文は、次のとおりです。
Authorization: Bearer access_token
次に例を示します。
curl https://instance_name.salesforce.com/services/data/v20.0/ -H
'Authorization: Bearer access_token'
セッション ID の認証
他のユーザのパスワードを処理していない場合は、OAuth 2.0 アクセストークンの代わ
りにセッション ID を使用できます。
1. セッション ID を取得します。たとえば、SOAP API login() コールは、セッショ
ン ID を返します。また、たとえば Apex の現在のコンテキストの一部として、
セッション ID を持つこともできます。開発中にテスト目的のためだけにセッ
ション ID が必要な場合、cURL コマンドで次のようにユーザ名パスワード OAuth
フローを使用できます。
curl https://login.salesforce.com/services/oauth2/token -d
"grant_type=password" -d "client_id=myclientid" -d
"client_secret=myclientsecret"
-d "[email protected]" -d
"password=mypassword123456"
クライアント ID、クライアントの秘密、ユーザ名、およびユーザセキュリティ
トークンを付加したパスワードが必要です。
2. リソースに要求を送信するときに、セッション ID を使用します。ID を token
値と置き換えます。構文は同じです。
Authorization: Bearer access_token
次に例を示します。
curl https://instance_name.salesforce.com/services/data/v20.0/
-H 'Authorization: Bearer access_token'
90
第 7 章 REST API
ステップ 3: cURL で HTTP 要求を送信する
Force.com REST API を操作するには、HTTP 要求を構築するようにクライアントアプリケー
ションを設定する必要があります (cURL を使用します)。
クライアントアプリケーションの設定
REST API は、HTTP GET および HTTP POST メソッドを使用して、JSON と XML コンテンツを
送信および取得するため、好みのツールまたは言語を使って簡単にクライアントアプ
リケーションを構築できます。HTTP 要求と応答の送受信を単純化するために、cURL と
いうコマンドラインツールを使用します。
cURL は、多くの Linux システムや Mac システムにあらかじめインストールされていま
す。Windows バージョンは、curl.haxx.se/ からダウンロードできます。Windows で
HTTPS を使用する場合、システムが SSL の cURL 要件を満たしていることを確認してく
ださい。
REST API リソースを使った HTTP 要求の送信
REST API リソースへの HTTP 要求には、次の情報が含まれている必要があります。
• HTTP メソッド (HEAD、GET、POST、PATCH、または DELETE)。
• 要求の認証に使用される OAuth 2.0 アクセストークン。トークンの取得方法につい
ては、「クイックスタート」 (ページ 254)を参照してください。
• リソースの形式 (XML または JSON)、または URI の .json または .xml 拡張子を示す
ために使用する HTTP ACCEPT ヘッダー。デフォルトは JSON です。
• Force.com REST リソース。
• 新しい情報でレコードを更新するなどの要求に必要な情報が含まれる JSON ファイ
ルまたは XML ファイル。
HTTP メソッドは、情報の取得や、レコードの作成、更新、削除など、目的のアクショ
ンを示すために使用されます。
• HEAD は、リソースメタデータの取得に使用されます。
• GET は、リソースに関する基本的なサマリー情報など、情報の取得に使用されま
す。
• POST は、新しいオブジェクトを作成するために使用されます。
91
第 7 章 REST API
• PATCH は、レコードを更新するために使用されます。
• DELETE は、レコードを削除するために使用されます。
リソースにアクセスするには、ヘッダー、メソッド、リソース名を含む HTTP 要求を送
信します。
たとえば、newaccount.json という JSON 形式のファイルを使用して、Account レコー
ドを作成するとします。これには、新しい Account レコードに保存される情報が含ま
れます。
{
"Name" : "test"
}
na1 に cURL を使用すると、要求は、次のようになります。
curl https://na1.salesforce.com/services/data/v20.0/sobjects/Account/
-H "Authorization: Bearer token -H "Content-Type: application/json"
-d "@newaccount.json"
HTTP 要求ヘッダーは次のようになります。
POST /services/data/v20.0/sobjects/Account HTTP/1.1
User-Agent: curl/7.19.7 (universal-apple-darwin10.0) libcurl/7.19.7
OpenSSL/0.9.8l zlib/1.2.3
Host: na7.salesforce.com
Accept: */*
Content-Length: 1411
Content-Type: application/json
Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
X-PrettyPrint:1
92
第 7 章 REST API
応答は次のようになります。
Date: Thu, 21 Oct 2010 22:16:22 GMT
Content-Length: 71
Location: /services/data/v20.0/sobjects/Account/001T000000NU96UIAT
Content-Type: application/json; charset=UTF-8 Server:
{ "id" : "001T000000NU96UIAT",
"errors" : [ ],
"success" : true }
リソースおよび対応する URI のリストについては、「リファレンス」を参照してくだ
さい。
ステップ 4: サンプルコードを実行する
このセクションでは、一連の REST 要求を作成します。要求の構築には cURL を使用し、
すべての要求と応答の形式として JSON を使用します。各要求では、REST リソースと共
にベース URI を使用します。これらの例のベース URI は
https://na1.salesforce.com/services/data です。詳細は、「Force.com REST リ
ソースの理解」を参照してください。
この例では、一連の REST 要求が次のシナリオで使用されます。
1. Salesforce バージョンを取得する。
2. Salesforce バージョンを使用して、使用可能なリソースのリストを取得する。
3. リソースの 1 つを使用して、使用可能なオブジェクトのリストを取得する。
4. オブジェクトの 1 つを選択して、そのメタデータの説明を取得する。
5. その同じオブジェクトの項目のリストを取得する。
6. SOQL クエリを実行して、Account レコードのすべての name 項目の値を取得す
る。
7. Account レコードの 1 つで請求先市区郡の情報 (BillingCity) を更新する。
93
第 7 章 REST API
Salesforce バージョンを取得する
はじめに、使用可能な各Salesforceバージョンに関する情報を取得します。これを行う
には、Versions リソースに要求を送信します。この場合、要求に認証は必要ありませ
ん。
curl https://na1.salesforce.com/services/data/
応答ヘッダーを含む、この要求の出力は次のとおりです。
Content-Length: 88
Content-Type: application/json;
charset=UTF-8 Server:
[
{
"version":"20.0",
"url":"/services/data/v20.0",
"label":"Winter '11"
}
...
]
出力は、すべての有効なバージョンで使用可能なリソースを指定します (結果には複
数の値が含まれる場合があります)。次に、これらのバージョンの 1 つを使用して、そ
れに含まれるリソースを検出します。
リソースのリストを取得する
次のステップは、Salesforce (この例ではバージョン 20.0) で使用可能なリソースのリスト
を取得します。これを行うには、Resources by Version の要求を送信します。
curl https://na1.salesforce.com/services/data/v20.0/ -H "Authorization:
Bearer access_token" -H "X-PrettyPrint:1"
94
第 7 章 REST API
この要求の出力は、次のとおりです。
{
"sobjects" : "/services/data/v20.0/sobjects",
"search" : "/services/data/v20.0/search",
"query" : "/services/data/v20.0/query",
"recent" : "/services/data/v20.0/recent"
}
この出力から、sobjects が、Salesforce バージョン 20.0 で使用可能なリソースの 1 つ
であることがわかります。このリソースを次の要求で使用し、使用可能なオブジェク
トを取得することができます。
使用可能なオブジェクトのリストを取得する
使用可能なリソースのリストを取得したので、使用可能なオブジェクトのリストを要
求できます。これを行うには、Describe Global の要求を送信します。
curl https://na1.salesforce.com/services/data/v20.0/sobjects/ -H
"Authorization: Bearer access_token" -H "X-PrettyPrint:1"
この要求の出力は、次のとおりです。
Transfer-Encoding: chunked
Content-Type: application/json;
charset=UTF-8 Server:
{
"encoding" : "UTF-8",
"maxBatchSize" : 200,
"sobjects" : [ {
"name" : "Account",
95
第 7 章 REST API
"label" : "Account",
"custom" : false,
"keyPrefix" : "001",
"updateable" : true,
"searchable" : true,
"labelPlural" : "Accounts",
"layoutable" : true,
"activateable" : false,
"urls" : { "sobject" : "/services/data/v20.0/sobjects/Account",
"describe" : "/services/data/v20.0/sobjects/Account/describe",
"rowTemplate" : "/services/data/v20.0/sobjects/Account/{ID}" },
"createable" : true,
"customSetting" : false,
"deletable" : true,
"deprecatedAndHidden" : false,
"feedEnabled" : false,
"mergeable" : true,
"queryable" : true,
"replicateable" : true,
"retrieveable" : true,
"undeletable" : true,
"triggerable" : true },
96
第 7 章 REST API
},
...
この出力から、Account オブジェクトが使用可能であることがわかります。Account オ
ブジェクトに関する詳細情報の取得については、次のステップで説明します。
オブジェクトの基本情報を取得する
Account オブジェクトを使用可能なリソースとして特定したため、そのメタデータに関
するいくつかの基本情報を取得できます。これを行うには、sObject Basic Information の
要求を送信します。
curl https://na1.salesforce.com/services/data/v20.0/sobjects/Account/
-H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"
この要求の出力は、次のとおりです。
{
"objectDescribe" :
{
"name" : "Account",
"updateable" : true,
"label" : "Account",
"keyPrefix" : "001",
...
"replicateable" : true,
"retrieveable" : true,
97
第 7 章 REST API
"undeletable" : true,
"triggerable" : true
},
"recentItems" :
[
{
"attributes" :
{
"type" : "Account",
"url" :
"/services/data/v20.0/sobjects/Account/001D000000INjVeIAL"
},
"Id" : "001D000000INjVeIAL",
"Name" : "asdasdasd"
},
...
]
}
この出力から、名前や表示ラベルなど、Account オブジェクトのいくつかの基本属性を
確認できます。最近使用された Account レコードのリストも取得されています。長さ
やデフォルト値など、その項目に関する詳細情報が必要な場合があるため、次のス
テップで、Account オブジェクトに関する詳細情報の取得について説明します。
98
第 7 章 REST API
項目のリストを取得する
Account オブジェクトのメタデータに関するいくつかの基本情報を取得したので、詳細
情報を取得できます。これを行うには、sObject Describe の要求を送信します。
curl
https://na1.salesforce.com/services/data/v20.0/sobjects/Account/describe/
-H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"
この要求の出力は、次のとおりです。
{
"name" : "Account",
"fields" :
[
{
"length" : 18,
"name" : "Id",
"type" : "id",
"defaultValue" : { "value" : null },
"updateable" : false,
"label" : "Account ID",
...
},
...
],
"updateable" : true,
"label" : "Account",
99
第 7 章 REST API
...
"urls" :
{
"uiEditTemplate" : "https://na1.salesforce.com/{ID}/e",
"sobject" : "/services/data/v20.0/sobjects/Account",
"uiDetailTemplate" : "https://na1.soma.salesforce.com/{ID}",
"describe" : "/services/data/v20.0/sobjects/Account/describe",
"rowTemplate" : "/services/data/v20.0/sobjects/Account/{ID}",
"uiNewRecord" : "https://na1.salesforce.com/001/e"
},
"childRelationships" :
[
{
"field" : "ParentId",
"deprecatedAndHidden" : false,
...
},
...
],
100
第 7 章 REST API
"createable" : true,
"customSetting" : false,
...
}
この出力から、その項目の属性や子リレーションなど、Account オブジェクトのさらに
詳細な情報を確認できます。これで、組織の Account オブジェクトに対する便利なク
エリと更新を作成するのに必要な情報を取得できました。次のステップでは、実際に
クエリと更新を実行します。
SOQL クエリを実行する
Account オブジェクトの項目名がわかったので、SOQL クエリを実行できます。例とし
て、今回は、すべての取引先名の値のリストを取得します。これを行うには、Query
要求を送信します。
curl
https://na1.salesforce.com/services/data/v20.0/query?q=SELECT+name+from+Account
-H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"
この要求の出力は、次のとおりです。
{
"done" : true,
"totalSize" : 14,
"records" :
[
{
"attributes" :
{
101
第 7 章 REST API
"type" : "Account",
"url" :
"/services/data/v20.0/sobjects/Account/001D000000IRFmaIAH"
},
"Name" : "Test 1"
},
{
"attributes" :
{
"type" : "Account",
"url" :
"/services/data/v20.0/sobjects/Account/001D000000IomazIAB"
},
"Name" : "Test 2"
},
...
]
}
この出力から使用可能な取引先名のリストを取得します。それぞれの名前の前にある
属性には取引先の ID が含まれます。次のステップでは、この情報を使用して、取引先
の 1 つを更新します。
メモ: SOQL についての詳細は、『Salesforce SOQL および SOSL リファレンスガイド』
を参照してください。
102
第 7 章 REST API
レコードの項目を更新する
取引先名と ID を把握できたので、レコードの 1 つを取得し、請求先市区郡の情報
(BillingCity) を更新できます。これを行うには、sObject Rows 要求を送信する必要があり
ます。オブジェクトを更新するには、市区郡に関する新しい情報を提供します。次の
情報を含む、patchaccount.json というテキストファイルを作成します。
{
"BillingCity" : "Fremont"
}
REST 要求に、この JSON ファイルを指定します。cURL 表記には、データを指定する場
合、—d オプションが必要です。詳細は、http://curl.haxx.se/docs/manpage.htmlを参照してく
ださい。
また、REST リソースを更新するために使用される PATCH メソッドを指定します。次
の cURL コマンドは、ID 項目を使用して指定された Account レコードを取得し、その市
区郡を更新します。
curl
https://na1.salesforce.com/services/data/v20.0/sobjects/Account/001D000000IroHJ
-H "Authorization: Bearer access_token" -H "X-PrettyPrint:1" -H
"Content-Type: application/json" --data-binary @patchaccount.json -X
PATCH
レスポンスボディはなく、ヘッダーのみが返されます。
HTTP/1.1 204 No Content
Server:
Content-Length: 0
その Account レコードのページを更新すると、請求先住所の市区郡が「Fremont」に変
更されていることを確認できます。
その他のリソース
• developer.salesforce.com で「Ruby」を検索してください。
103
第 7 章 REST API
• Ruby での使用開始は、『Force.com Cookbook』のレシピを参照してください。
• Force.com REST API のディスカッションボード
ベストプラクティス
このセクションで説明するベストプラクティスを考慮してください。
JSON と XML のサポート
JSON は REST API リクエストボディとレスポンスボディのデフォルトですが、XML もサ
ポートされています。HTTP ACCEPT ヘッダーを使用して、JSON または XML のいずれかを
指定できます。XML 逐次化は SOAP API と類似しています。XML 要求は UTF-8 および UTF-16
でサポートされ、XML 応答は UTF-8 で提供されます。
日付と時刻の形式
要求と応答内の日時情報は ISO8601 形式を使用して指定します。
圧縮
REST API は、HTTP 1.1 仕様で定義された標準を使用した要求と応答の圧縮をサポートし
ています。圧縮は、いくつかのクライアントでは自動的にサポートされており、他の
クライアントにも手動で追加できます。パフォーマンス向上のため、HTTP 1.1 圧縮を
サポートできるクライアントを使用することをお勧めします。
応答は、クライアントが要求に Accept-Encoding: gzip または Accept-Encoding:
deflate HTTP ヘッダーを使用していれば圧縮されます。REST API は応答を圧縮し、応
答のヘッダーに Accept-Encoding: gzip または Accept-Encoding: deflate を
含めます。
要求に Content-Encoding: gzip または Content-Encoding: deflate ヘッダー
を指定した場合、圧縮した要求データを送信できます。REST API は、サポートされて
いる圧縮アルゴリズムを含む Content-Encoding 要求ヘッダーが指定されていれば、
受信した要求の内容を圧縮解除します。
104
第 7 章 REST API
リソース
REST API に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• REST API 開発者ガイド
• REST API 開発者早見表
• Salesforce オブジェクトリファレンス
• API とインテグレーションに関するフォーラム
105
第8章
メタデータ API
メタデータ API は、Salesforce 組織のメタデータを操作するための API を提供します。メ
タデータ API は、.zip ファイル経由で大量のメタデータ情報をリリースおよび取得する
コールを提供するファイルベースの API、または個々のメタデータコンポーネントを
作成、更新、および削除するコールを提供するコンポーネントベースの API から使用
できます。
メタデータ API を使用するケース
メタデータ API を使用して、組織のカスタマイズを取得、リリース、作成、更新、ま
たは削除します。最も一般的な使い方は、Sandbox またはテスト組織から本番環境へ
の変更の移行です。メタデータ API はカスタマイズを管理し、データ自体ではなくメ
タデータモデルを管理できるツールを構築するためのものです。
Force.com IDE または Force.com 移行ツールを使用すると、最も簡単にメタデータ API の機
能にアクセスできます。これらのツールはメタデータ APIの上位に構築され、メタデー
タ API との連携タスクを簡略化するために標準 Eclipse および Ant ツールを使用します。
Eclipse プラットフォームで開発された Force.com IDE は、統合された開発環境に慣れてい
るプログラマに快適な環境を提供し、IDE 内でコード記述、コンパイル、テスト、リ
リースのすべてを行うことができます。Force.com 移行ツールは、スクリプトまたはコ
マンドラインユーティリティを使用してローカルディレクトリとSalesforce組織間でメ
タデータを移動する場合に最適です。
サポート対象のエディションとプラットフォーム
メタデータ API は、Enterprise Edition、Performance Edition、Unlimited Edition、Developer Edition、
または Database.com で使用できます。既存の Salesforce のお客様が Enterprise Edition、
Unlimited Edition、または Performance Edition にアップグレードする場合は、担当者にご連
絡ください。
107
第 8 章 メタデータ API
クイックスタート
Force.com IDE または Force.com 移行ツールを使用すると、最も簡単にメタデータ API の機
能にアクセスできます。これらのツールはメタデータ APIの上位に構築され、メタデー
タ API との連携タスクを簡略化するために標準 Eclipse および Ant ツールを使用します。
Eclipse プラットフォームで開発された Force.com IDE は、統合された開発環境に慣れてい
るプログラマに快適な環境を提供し、IDE 内でコード記述、コンパイル、テスト、リ
リースのすべてを行うことができます。Force.com 移行ツールは、スクリプトまたはコ
マンドラインユーティリティを使用してローカルディレクトリとSalesforce組織間でメ
タデータを移動する場合に最適です。Force.com IDE または Force.com 移行ツールについ
ての詳細は、developer.salesforce.com を参照してください。
ただし、メタデータ API の基礎となるコールは、独自のクライアントアプリケーショ
ンを構築する必要があるユーザが直接使用できるよう公開されています。このクイッ
クスタートでは、組織のカスタマイズを管理するためにメタデータ API を直接使用す
るアプリケーションの作成を開始するのに必要なすべての情報について説明します。
このクイックスタートでは、ファイルベースの開発を開始する方法について説明しま
す。CRUD ベースの開発の例については、「同期コールを使用した CRUD ベース開発用
の Java サンプル」を参照してください。
前提条件
メタデータ API を使用し始める前に、次の前提条件を必ず実行してください。
• 開発環境を作成します。
本番組織の厳密なレプリカである Sandbox を使用することを強くお勧めします。
Enterprise Edition、Unlimited Edition、および Performance Edition には無料の開発者 Sandbox
が付属しています。詳細は、
http://www.salesforce.com/platform/cloud-infrastructure/sandbox.jsp
を参照してください。
また、ユーザは Enterprise Edition で使用できるすべての機能へのアクセスを提供する
Developer Edition 組織を使用できます。ただし、ユーザ数およびストレージ容量には
制限があります。Developer Edition 組織は、本番組織のコピーではありませんが、組
織のデータに影響を与えることなくソリューションを構築およびテストできる環
境を提供します。Developer Edition のアカウントは、
http://developer.salesforce.com/signup から無料で入手できます。
108
第 8 章 メタデータ API
• 「API の有効化」および「すべてのデータの編集」権限を持つユーザを特定しま
す。これらの権限はメタデータ API コールにアクセスするために必要です。
• SOAP クライアントをインストールします。メタデータ API は、Visual Studio® .NET や
Force.com Web Service Connector (WSC) などに限らず、現在の SOAP 開発環境で動作しま
す。
このドキュメントでは、WSC および JDK 6 (Java Platform Standard Edition Development Kit
6) に基づく Java の例を使用しています。サンプルを実行するには、まず
mvnrepository.com/artifact/com.force.api/force-wsc/ から最新の force-wsc JAR ファイルとそ
の連動関係 (連動関係リストはバージョンを選択したときにページに表示されます)
をダウンロードします。
メモ: 開発プラットフォームは、SOAP の実装によって異なります。特定の開
発プラットフォームにおける実装の相違点により、メタデータ APIの一部また
はすべての機能にアクセスできないことがあります。
ステップ 1: 組織の Web サービス WSDL の生成または
取得
メタデータ API コールにアクセスするには、Web Service Description Language (WSDL) ファ
イルが必要です。WSDL ファイルは、使用できる Web サービスを定義します。開発プ
ラットフォームではこの WSDL を使用してスタブコードを生成し、WSDL が定義する
Web サービスにアクセスします。組織の Salesforce システム管理者から WSDL ファイル
を取得することも、WSDL ダウンロードページへのアクセス権限がある場合はSalesforce
ユーザインターフェースで自分で生成することもできます。WSDL の詳細は、
http://www.w3.org/TR/wsdl を参照してください。
メタデータ API コールにアクセスするには、Enterprise WSDL および Partner WSDL で定義さ
れている login() コールを使用して Web サービスを使用するための認証を行う必要
があります。そのため、これらの WSDL の 1 つを取得する必要もあります。
「すべてのデータの編集」権限を持つユーザなら誰でも WSDL ファイルをダウンロー
ドし、Salesforceプラットフォームを統合および拡張できます (システム管理者プロファ
イルにこの権限が与えられます)。
ステップ 3: Java サンプルコードの説明 (ページ 111)のサンプルコードでは Enterprise WSDL
を使用していますが、Partner WSDL でも同様に適切に機能します。
組織のメタデータおよび Enterprise WSDL ファイルを生成する手順は、次のとおりです。
109
第 8 章 メタデータ API
1. Salesforce アカウントにログインします。「すべてのデータの編集」権限を持つ
管理者またはユーザとしてログインします。
2. [設定] から、[開発] > [API] をクリックします。
3. [メタデータ WSDL の生成] をクリックして、ファイルシステムに XML WSDL ファ
イルを保存します。
4. [Enterprise WSDL の生成] をクリックして、ファイルシステムに XML WSDL ファイ
ルを保存します。
ステップ 2: 開発プラットフォームへの WSDL ファイル
のインポート
WSDL ファイルを作成したら、開発環境でクライアント Web サービスアプリケーショ
ンの構築に必要なオブジェクトを生成できるよう、WSDL ファイルを開発プラット
フォームにインポートする必要があります。このセクションでは、WSC のサンプルに
ついて説明します。その他の開発環境の指示については、プラットフォームの製品マ
ニュアルを参照してください。
メモ: WSDL ファイルをインポートするプロセスは、メタデータファイルおよび
Enterprise WSDL ファイルの場合と同じです。
Java 環境での使用方法 (WSC)
Java 環境は、サーバ側オブジェクトのプロキシとして機能する Java オブジェクトを使
用して、API にアクセスします。API を使用する前に、まず組織の WSDL ファイルから
これらのオブジェクトを生成する必要があります。
SOAP クライアントには、このプロセスで使用する独自のツールがあります。WSC で
は、wsdlc ユーティリティを使用します。
メモ: wsdlc を実行する前に、システムに WSC JAR ファイルがインストール済み
であり、クラスパスで参照されている必要があります。
mvnrepository.com/artifact/com.force.api/force-wsc/ から最新の force-wsc JAR ファイルとそ
の連動関係 (連動関係リストはバージョンを選択したときにページに表示されま
す) をダウンロードできます。
110
第 8 章 メタデータ API
wsdlc の基本構文は、次のとおりです。
java -classpath pathToWsc;pathToWscDependencies
com.sforce.ws.tools.wsdlc pathToWsdl/WsdlFilename
pathToOutputJar/OutputJarFilename
たとえば、Window の場合、次のようになります。
java –classpath force-wsc-30.0.0.jar;ST4-4.0.7.jar;antlr-runtime-3.5.jar
com.sforce.ws.tools.wsdlc metadata.wsdl metadata.jar
Mac OS X および UNIX では、クラスパスの項目間にセミコロンではなくコロンを使用し
ます。
java –classpath force-wsc-30.0.0.jar:ST4-4.0.7.jar:antlr-runtime-3.5.jar
com.sforce.ws.tools.wsdlc metadata.wsdl metadata.jar
wsdlc は、クライアントアプリケーションの作成で使用する JAR ファイル、Java ソー
スコード、およびバイトコードファイルを生成します。Enterprise WSDL でもこのプロセ
スを繰り返し、enterprise.JAR ファイルを作成します。
ステップ 3: Java サンプルコードの説明
WSDL ファイルをインポートすると、メタデータ API を使用するクライアントアプリ
ケーションの構築を開始できます。このサンプルは、独自のコードを記述するための
出発点として適しています。
サンプルを実行する前に、プロジェクトとコードを次のように変更します。
1. WSC JAR、その連動関係、および WSDL から生成した JAR ファイルを含めます。
メモ: WSC には他の連動関係がありますが、次のサンプルでは Rhino
(js-1.7R2.jar) のみが必要です。これは、mvnrepository.com/artifact/rhino/js
からダウンロードできます。
2. 自分のユーザ名とパスワードを使って、MetadataLoginUtil.login() メソッ
ドの USERNAME 変数と PASSWORD 変数を更新します。現在の IP アドレスが組織の
信頼済み IP 範囲内にない場合は、セキュリティトークンをパスワードに追加す
る必要があります。
3. Sandbox を使用している場合は、必ずログイン URL を変更してください。
111
第 8 章 メタデータ API
ログインユーティリティ
Java ユーザは、ConnectorConfig を使用して、Enterprise API、Partner API、および Metadata
SOAP API に接続できます。MetadataLoginUtil は ConnectorConfig オブジェクト
を作成し、Enterprise WSDL の login メソッドを使用してログインします。次に、
sessionId と metadataServerUrl を取得して ConnectorConfig を作成し、メタ
データ API のエンドポイントに接続します。ConnectorConfig は WSC で定義されて
います。
MetadataLoginUtil クラスは、サンプルの他の部分からログインコードを抽象化す
るため、Salesforce API ごとに変更を行わずにこのコードの一部を再利用できます。
import com.sforce.soap.enterprise.EnterpriseConnection;
import com.sforce.soap.enterprise.LoginResult;
import com.sforce.soap.metadata.MetadataConnection;
import com.sforce.ws.ConnectionException;
import com.sforce.ws.ConnectorConfig;
/**
* Login utility.
*/
public class MetadataLoginUtil {
public static MetadataConnection login() throws ConnectionException
{
final String USERNAME = "[email protected]";
// This is only a sample. Hard coding passwords in source files
is a bad practice.
final String PASSWORD = "password";
112
第 8 章 メタデータ API
final String URL =
"https://login.salesforce.com/services/Soap/c/33.0";
final LoginResult loginResult = loginToSalesforce(USERNAME,
PASSWORD, URL);
return createMetadataConnection(loginResult);
}
private static MetadataConnection createMetadataConnection(
final LoginResult loginResult) throws ConnectionException
{
final ConnectorConfig config = new ConnectorConfig();
config.setServiceEndpoint(loginResult.getMetadataServerUrl());
config.setSessionId(loginResult.getSessionId());
return new MetadataConnection(config);
}
private static LoginResult loginToSalesforce(
final String username,
final String password,
final String loginUrl) throws ConnectionException {
final ConnectorConfig config = new ConnectorConfig();
config.setAuthEndpoint(loginUrl);
config.setServiceEndpoint(loginUrl);
113
第 8 章 メタデータ API
config.setManualLogin(true);
return (new EnterpriseConnection(config)).login(username,
password);
}
}
ファイルベース開発用の Java のサンプルコード
サンプルコードは、ログインユーティリティを使用してログインします。次に、取
得、リリース、および終了のメニューを表示します。
retrieve() コールおよび deploy() コールは両方とも components.zip という名
前の .zip ファイルを処理します。retrieve() コールは組織のコンポーネントを
components.zip に取得し、deploy() コールは components.zip のコンポーネン
トを組織にリリースします。コンピュータにサンプルを保存して実行する場合は、後
でリリースできる components.zip ファイルを含めることができるように、まず取
得オプションを実行します。retrieve コールの後、サンプルは、操作が完了するまで
checkRetrieveStatus() コールをループします。同様に、deploy コールの後、サン
プルは、操作が完了するまで checkDeployStatus() チェックをループします。
retrieve() コールは、マニフェストファイルを使用して組織から取得するコンポー
ネントを決定します。package.xml マニフェストファイルのサンプルは次のとおり
です。マニフェストファイルの構造についての詳細は、「Zip ファイルの使用」を参
照してください。このサンプルでは、マニフェストファイルはすべてのカスタムオブ
ジェクト、カスタムタブ、およびページレイアウトを取得します。
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>*</members>
<name>CustomObject</name>
</types>
114
第 8 章 メタデータ API
<types>
<members>*</members>
<name>CustomTab</name>
</types>
<types>
<members>*</members>
<name>Layout</name>
</types>
<version>33.0</version>
</Package>
API コールに続く、エラー処理コードに注意してください。
import java.io.*;
import java.nio.channels.Channels;
import java.nio.channels.FileChannel;
import java.nio.channels.ReadableByteChannel;
import java.rmi.RemoteException;
import java.util.*;
import javax.xml.parsers.*;
import org.w3c.dom.*;
import org.xml.sax.SAXException;
115
第 8 章 メタデータ API
import com.sforce.soap.metadata.*;
/**
* Sample that logs in and shows a menu of retrieve and deploy metadata
options.
*/
public class FileBasedDeployAndRetrieve {
private MetadataConnection metadataConnection;
private static final String ZIP_FILE = "components.zip";
// manifest file that controls which components get retrieved
private static final String MANIFEST_FILE = "package.xml";
private static final double API_VERSION = 29.0;
// one second in milliseconds
private static final long ONE_SECOND = 1000;
// maximum number of attempts to deploy the zip file
116
第 8 章 メタデータ API
private static final int MAX_NUM_POLL_REQUESTS = 50;
private BufferedReader reader = new BufferedReader(new
InputStreamReader(System.in));
public static void main(String[] args) throws Exception {
FileBasedDeployAndRetrieve sample = new
FileBasedDeployAndRetrieve();
sample.run();
}
public FileBasedDeployAndRetrieve() {
}
private void run() throws Exception {
this.metadataConnection = MetadataLoginUtil.login();
// Show the options to retrieve or deploy until user exits
String choice = getUsersChoice();
while (choice != null && !choice.equals("99")) {
if (choice.equals("1")) {
retrieveZip();
} else if (choice.equals("2")) {
117
第 8 章 メタデータ API
deployZip();
} else {
break;
}
// show the options again
choice = getUsersChoice();
}
}
/*
* Utility method to present options to retrieve or deploy.
*/
private String getUsersChoice() throws IOException {
System.out.println(" 1: Retrieve");
System.out.println(" 2: Deploy");
System.out.println("99: Exit");
System.out.println();
System.out.print("Enter 1 to retrieve, 2 to deploy, or 99 to
exit: ");
// wait for the user input.
String choice = reader.readLine();
return choice != null ? choice.trim() : "";
}
118
第 8 章 メタデータ API
private void deployZip() throws Exception {
byte zipBytes[] = readZipFile();
DeployOptions deployOptions = new DeployOptions();
deployOptions.setPerformRetrieve(false);
deployOptions.setRollbackOnError(true);
AsyncResult asyncResult = metadataConnection.deploy(zipBytes,
deployOptions);
DeployResult result =
waitForDeployCompletion(asyncResult.getId());
if (!result.isSuccess()) {
printErrors(result, "Final list of failures:\n");
throw new Exception("The files were not successfully
deployed");
}
System.out.println("The file " + ZIP_FILE + " was successfully
deployed\n");
}
/*
* Read the zip file contents into a byte array.
*/
private byte[] readZipFile() throws Exception {
byte[] result = null;
119
第 8 章 メタデータ API
// We assume here that you have a deploy.zip file.
// See the retrieve sample for how to retrieve a zip file.
File zipFile = new File(ZIP_FILE);
if (!zipFile.exists() || !zipFile.isFile()) {
throw new Exception("Cannot find the zip file for deploy()
on path:"
+ zipFile.getAbsolutePath());
}
FileInputStream fileInputStream = new FileInputStream(zipFile);
try {
ByteArrayOutputStream bos = new ByteArrayOutputStream();
byte[] buffer = new byte[4096];
int bytesRead = 0;
while (-1 != (bytesRead = fileInputStream.read(buffer)))
{
bos.write(buffer, 0, bytesRead);
}
result = bos.toByteArray();
} finally {
fileInputStream.close();
120
第 8 章 メタデータ API
}
return result;
}
/*
* Print out any errors, if any, related to the deploy.
* @param result - DeployResult
*/
private void printErrors(DeployResult result, String messageHeader)
{
DeployDetails details = result.getDetails();
StringBuilder stringBuilder = new StringBuilder();
if (details != null) {
DeployMessage[] componentFailures =
details.getComponentFailures();
for (DeployMessage failure : componentFailures) {
String loc = "(" + failure.getLineNumber() + ", " +
failure.getColumnNumber();
if (loc.length() == 0 &&
!failure.getFileName().equals(failure.getFullName()))
{
loc = "(" + failure.getFullName() + ")";
}
stringBuilder.append(failure.getFileName() + loc + ":"
121
第 8 章 メタデータ API
+ failure.getProblem()).append('\n');
}
RunTestsResult rtr = details.getRunTestResult();
if (rtr.getFailures() != null) {
for (RunTestFailure failure : rtr.getFailures()) {
String n = (failure.getNamespace() == null ? "" :
(failure.getNamespace() + ".")) +
failure.getName();
stringBuilder.append("Test failure, method: " + n
+ "." +
failure.getMethodName() + " -- " +
failure.getMessage() +
" stack " + failure.getStackTrace() +
"\n\n");
}
}
if (rtr.getCodeCoverageWarnings() != null) {
for (CodeCoverageWarning ccw :
rtr.getCodeCoverageWarnings()) {
stringBuilder.append("Code coverage issue");
if (ccw.getName() != null) {
String n = (ccw.getNamespace() == null ? "" :
(ccw.getNamespace() + ".")) + ccw.getName();
122
第 8 章 メタデータ API
stringBuilder.append(", class: " + n);
}
stringBuilder.append(" -- " + ccw.getMessage() +
"\n");
}
}
}
if (stringBuilder.length() > 0) {
stringBuilder.insert(0, messageHeader);
System.out.println(stringBuilder.toString());
}
}
private void retrieveZip() throws Exception {
RetrieveRequest retrieveRequest = new RetrieveRequest();
// The version in package.xml overrides the version in
RetrieveRequest
retrieveRequest.setApiVersion(API_VERSION);
setUnpackaged(retrieveRequest);
AsyncResult asyncResult =
metadataConnection.retrieve(retrieveRequest);
RetrieveResult result = waitForRetrieveCompletion(asyncResult);
123
第 8 章 メタデータ API
if (result.getStatus() == RetrieveStatus.Failed) {
throw new Exception(result.getErrorStatusCode() + " msg:
" +
result.getErrorMessage());
} else if (result.getStatus() == RetrieveStatus.Succeeded) {
// Print out any warning messages
StringBuilder stringBuilder = new StringBuilder();
if (result.getMessages() != null) {
for (RetrieveMessage rm : result.getMessages()) {
stringBuilder.append(rm.getFileName() + " - " +
rm.getProblem() + "\n");
}
}
if (stringBuilder.length() > 0) {
System.out.println("Retrieve warnings:\n" + stringBuilder);
}
System.out.println("Writing results to zip file");
File resultsFile = new File(ZIP_FILE);
FileOutputStream os = new FileOutputStream(resultsFile);
124
第 8 章 メタデータ API
try {
os.write(result.getZipFile());
} finally {
os.close();
}
}
}
private DeployResult waitForDeployCompletion(String asyncResultId)
throws Exception {
int poll = 0;
long waitTimeMilliSecs = ONE_SECOND;
DeployResult deployResult;
boolean fetchDetails;
do {
Thread.sleep(waitTimeMilliSecs);
// double the wait time for the next iteration
waitTimeMilliSecs *= 2;
if (poll++ > MAX_NUM_POLL_REQUESTS) {
throw new Exception(
"Request timed out. If this is a large set of
125
第 8 章 メタデータ API
metadata components, " +
"ensure that MAX_NUM_POLL_REQUESTS is sufficient.");
}
// Fetch in-progress details once for every 3 polls
fetchDetails = (poll % 3 == 0);
deployResult =
metadataConnection.checkDeployStatus(asyncResultId, fetchDetails);
System.out.println("Status is: " +
deployResult.getStatus());
if (!deployResult.isDone() && fetchDetails) {
printErrors(deployResult, "Failures for deployment in
progress:\n");
}
}
while (!deployResult.isDone());
if (!deployResult.isSuccess() &&
deployResult.getErrorStatusCode() != null) {
throw new Exception(deployResult.getErrorStatusCode() + "
msg: " +
deployResult.getErrorMessage());
}
126
第 8 章 メタデータ API
if (!fetchDetails) {
// Get the final result with details if we didn't do it
in the last attempt.
deployResult =
metadataConnection.checkDeployStatus(asyncResultId, true);
}
return deployResult;
}
private RetrieveResult waitForRetrieveCompletion(AsyncResult
asyncResult) throws Exception {
// Wait for the retrieve to complete
int poll = 0;
long waitTimeMilliSecs = ONE_SECOND;
String asyncResultId = asyncResult.getId();
RetrieveResult result = null;
do {
Thread.sleep(waitTimeMilliSecs);
// Double the wait time for the next iteration
waitTimeMilliSecs *= 2;
if (poll++ > MAX_NUM_POLL_REQUESTS) {
throw new Exception("Request timed out.
large set " +
127
If this is a
第 8 章 メタデータ API
"of metadata components, check that the time allowed
" +
"by MAX_NUM_POLL_REQUESTS is sufficient.");
}
result = metadataConnection.checkRetrieveStatus(
asyncResultId);
System.out.println("Retrieve Status: " +
result.getStatus());
} while (!result.isDone());
return result;
}
private void setUnpackaged(RetrieveRequest request) throws Exception
{
// Edit the path, if necessary, if your package.xml file is
located elsewhere
File unpackedManifest = new File(MANIFEST_FILE);
System.out.println("Manifest file: " +
unpackedManifest.getAbsolutePath());
if (!unpackedManifest.exists() || !unpackedManifest.isFile())
{
throw new Exception("Should provide a valid retrieve
manifest " +
"for unpackaged content. Looking for " +
128
第 8 章 メタデータ API
unpackedManifest.getAbsolutePath());
}
// Note that we use the fully quualified class name because
// of a collision with the java.lang.Package class
com.sforce.soap.metadata.Package p =
parsePackageManifest(unpackedManifest);
request.setUnpackaged(p);
}
private com.sforce.soap.metadata.Package parsePackageManifest(File
file)
throws ParserConfigurationException, IOException,
SAXException {
com.sforce.soap.metadata.Package packageManifest = null;
List<PackageTypeMembers> listPackageTypes = new
ArrayList<PackageTypeMembers>();
DocumentBuilder db =
DocumentBuilderFactory.newInstance().newDocumentBuilder();
InputStream inputStream = new FileInputStream(file);
Element d = db.parse(inputStream).getDocumentElement();
for (Node c = d.getFirstChild(); c != null; c =
c.getNextSibling()) {
if (c instanceof Element) {
129
第 8 章 メタデータ API
Element ce = (Element) c;
NodeList nodeList = ce.getElementsByTagName("name");
if (nodeList.getLength() == 0) {
continue;
}
String name = nodeList.item(0).getTextContent();
NodeList m = ce.getElementsByTagName("members");
List<String> members = new ArrayList<String>();
for (int i = 0; i < m.getLength(); i++) {
Node mm = m.item(i);
members.add(mm.getTextContent());
}
PackageTypeMembers packageTypes = new
PackageTypeMembers();
packageTypes.setName(name);
packageTypes.setMembers(members.toArray(new
String[members.size()]));
listPackageTypes.add(packageTypes);
}
}
packageManifest = new com.sforce.soap.metadata.Package();
PackageTypeMembers[] packageTypesArray =
new PackageTypeMembers[listPackageTypes.size()];
130
第 8 章 メタデータ API
packageManifest.setTypes(listPackageTypes.toArray(packageTypesArray));
packageManifest.setVersion(API_VERSION + "");
return packageManifest;
}
}
ベストプラクティス
このセクションのベストプラクティスを考慮してください。
メタデータの変更のテスト
メタデータの変更は、本番組織で直接検証せずに、まずテスト環境で検証する必要が
あります。
本番組織の厳密なレプリカである Sandbox を使用することを強くお勧めします。Enterprise
Edition、Unlimited Edition、および Performance Edition には無料の開発者 Sandbox が付属して
います。詳細は、
http://www.salesforce.com/platform/cloud-infrastructure/sandbox.jsp
を参照してください。
また、ユーザは Enterprise Edition で使用できるすべての機能へのアクセスを提供する
Developer Edition 組織を使用できます。ただし、ユーザ数およびストレージ容量には制
限があります。Developer Edition 組織は、本番組織のコピーではありませんが、組織の
データに影響を与えることなくソリューションを構築およびテストできる環境を提供
します。Developer Edition のアカウントは、
http://developer.salesforce.com/signup から無料で入手できます。
その他の一般的なメタデータの問題
最も一般的なメタデータの問題として、次のようなものがあります。
131
第 8 章 メタデータ API
• 標準オブジェクトのカスタム項目の取得 — package.xml でワイルドカード記号
を使用してすべてのオブジェクトを取得する場合、標準オブジェクトや標準オブ
ジェクトのカスタム項目は取得されません。標準オブジェクトのカスタム項目を
取得するには、package.xml でコンポーネントの名前を指定する必要がありま
す。
• プロファイルまたは権限セットと項目レベルセキュリティ — 取得したプロファイ
ルまたは権限セットの内容は、retrieve 要求の他の内容に応じて異なります。たと
えば、カスタムオブジェクトに含まれている項目の項目レベルセキュリティ情報
が、プロファイルまたは権限セットと同時に返されます。詳細は、『メタデータ
API 開発者ガイド』の「Profile」および「PermissionSet」を参照してください。
• ワークフロー — .workflow ファイルは、オブジェクトに関連付けられた、
WorkflowAlert、WorkflowFieldUpdate、WorkflowOutboundMessage、WorkflowRule、WorkflowTask
など、個々のワークフローコンポーネントのコンテナです。すべてのワークフロー
を取得するには、次の XML を package.xml に含めます。
<types>
<members>*</members>
<name>Workflow</name>
</types>
• オブジェクト定義に依存するコンポーネントの取得またはリリース — メタデータ
コンポーネント CustomField、Picklist、RecordType、Weblink、および
ValidationRule の定義は、特定のオブジェクトに依存します。つまり、
package.xml ではコンポーネント名をドットとオブジェクト名で修飾する必要が
あります。また、ワイルドカード記号は使用しないでください。
• 個人フォルダ — ユーザの個人フォルダは、レポートとドキュメントのいずれもメ
タデータ APIでは公開されません。レポートまたはドキュメントを移行するには、
公開フォルダに移動する必要があります。
リソース
メタデータ API に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
132
第 8 章 メタデータ API
• メタデータ API 開発者ガイド
• Migration Tool Guide (移行ツールガイド)
• API とインテグレーションに関するフォーラム
133
第9章
Bulk API
Bulk API では、プログラムを介して、組織のデータを Salesforce に効率よく読み込んだ
り、そこから取得したりできます。
Bulk API を使用するケース
Bulk API は、REST 規則に基づいており、大規模データセットの読み込みまたは削除用に
最適化されています。Bulk API を使用すると、Salesforce によりバックグラウンドで処理
される複数のバッチを送信することにより、多数のレコードを非同期でクエリ、挿
入、更新、更新/挿入または削除できます。Bulk API は、千から百万単位のレコードの
データを簡単に読み込めるように設計されています。
Bulk API を使用してレコードセットを処理するには、1 つ以上のバッチを含むジョブを
作成します。このジョブは、処理されるオブジェクトと使用されるアクションの種別
(クエリ、挿入、更新/挿入、更新、または削除) を指定します。バッチは、HTTP POST 要
求でサーバに送信されるレコードセットです。各バッチはサーバによって独自に処理
されます。受信した順序で処理されるとは限りません。バッチは並列処理が可能で
す。データセット全体をどのように適切な数のバッチに分割するかは、クライアント
側で決定されます。
サポート対象のエディションとプラットフォーム
Bulk API を使用するには、組織で Enterprise Edition、Performance Edition、Unlimited Edition、
または Developer Edition を使用している必要があります。既存の Salesforce のお客様が
Enterprise Edition、Unlimited Edition、または Performance Edition にアップグレードする場合
は、担当者にご連絡ください。
135
第 9 章 Bulk API
クイックスタート
このセクションでは、クイックスタートのサンプルを使用して、REST ベースの Bulk API
で新しい取引先責任者レコードを挿入する HTTP 要求を作成します。ログインから、レ
コードの送信、状況の確認、結果の取得まで、手順を順番に説明します。
メモ: インテグレーションまたはその他のクライアントアプリケーションを作成
する前に、次のことを実行してください。
• 製品ドキュメントに従って、開発プラットフォームをインストールする。
• このクイックスタートを開始する前に、すべての手順に目を通す。このガイ
ドの他の部分を確認しておくと、用語や概念を把握できます。
Salesforce Developer Edition 組織の設定
まず、Salesforce Developer Edition 組織を取得し、Bulk API を有効にします。
1. Salesforce Developer Edition 組織を取得します。
まだ開発者コミュニティのメンバーでない場合、
developer.salesforce.com/signup にアクセスし、Developer Edition アカウ
ントのサインアップの説明に従ってください。すでに Enterprise Edition、Unlimited
Edition、または Performance Edition のアカウントを所有している場合でも、組織の
使用中のデータを保護するために、サンプルデータに対するソリューションの
開発、ステージングおよびテストには Developer Edition を使用することを強くお
勧めします。これは、特に、(データをただ参照するだけのアプリケーションに
対し) データをクエリ、挿入、更新または削除するアプリケーションの場合に
該当します。
2. Bulk API を有効にします。
「API の有効化」権限が必要です。この権限は、システム管理者プロファイルで
有効にします。
クライアントアプリケーションの設定
Bulk API は HTTP GET および HTTP POST メソッドを使用して CSV と XML のコンテンツを送受
信します。そのため、任意のツールや言語を使用してクライアントアプリケーション
136
第 9 章 Bulk API
を非常に簡単に構築することができます。このクイックスタートでは、HTTP 要求と応
答の送受信を単純化するために、cURL というコマンドラインツールを使用します。
cURL は、多くの Linux システムや Mac システムにあらかじめインストールされていま
す。Windows バージョンは、curl.haxx.se/ からダウンロードできます。Windows で
HTTPS を使用する場合、システムが SSL の cURL 要件を満たしていることを確認してく
ださい。
メモ: cURL はオープンソースのツールで、Salesforceではサポートされていません。
Mac および Linux システムでのセッション ID のエスケープまたは一重引用符の使用
REST リソースで cURL の例を実行するとき、セッション ID 引数の感嘆符の特殊文字
によって、Mac および Linux システムでエラーが発生する場合があります。このエ
ラーの発生を回避するには、次のいずれかを実行します。
• セッション ID が二重引用符で囲まれている場合、セッション ID の感嘆符 (!) 特
殊文字の前にバックスラッシュを挿入して (\!) エスケープします。たとえば、
この cURL コマンドのセッション ID 文字列では、感嘆符 (!) がエスケープされて
います。
curl https://instance_name.salesforce.com/services/data/v33.0/
-H "Authorization: Bearer
00D50000000IehZ\!AQcAQH0dMHZfz972Szmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1E6
LYUfiDUkWe6H34r1AAwOR8B8fLEz6n04NPGRrq0FM"
• セッション ID を一重引用符で囲みます。次に例を示します。
curl https://instance_name.salesforce.com/services/data/v33.0/
-H 'Authorization: Bearer sessionID'
cURL を使用した HTTP 要求の送信
cURL の設定が完了したら、Bulk API に HTTP 要求を送信できるようになります。Bulk API
で処理を実行するには、URI に HTTP 要求を送信します。
HTTP 要求を送信する URI は、次の形式で指定します。
Web_Services_SOAP_endpoint_instance_name/services/async/APIversion/Resource_address
137
第 9 章 Bulk API
API のバージョンより後ろの部分 (Resource_address) は、処理するジョブやバッチ
によって変わります。
Bulk API の最も簡単な使用方法は、CSV ファイルを使用してデータローダでレコードの
処理ができるようにすることです。データローダを使用すれば、HTTP 要求を独自に作
成したり、クライアントアプリケーションを新たに開発したりする必要はありませ
ん。Java を使用してクライアントアプリケーションを開発する例は、「Java を使用し
たサンプルクライアントアプリケーション」を参照してください。
ステップ 1: SOAP API を使用したログイン
Bulk API はログイン処理をサポートしていません。ログインは、SOAP API を使用して実
行する必要があります。
cURL を使用して Salesforce にログインする手順は、次のとおりです。
1. login.txt という名前のテキストファイルを作成し、次のテキストを含めま
す。
<?xml version="1.0" encoding="utf-8" ?>
<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Body>
<n1:login xmlns:n1="urn:partner.soap.sforce.com">
<n1:username>your_username</n1:username>
<n1:password>your_password</n1:password>
</n1:login>
</env:Body>
</env:Envelope>
138
第 9 章 Bulk API
2. your_username と your_password の箇所を、Salesforce のユーザ名とパスワー
ドで置き換えます。
3. コマンドラインウィンドウを使用して、次の cURL コマンドを実行します。
curl https://login.salesforce.com/services/Soap/u/33.0 -H
"Content-Type: text/xml; charset=UTF-8" -H "SOAPAction: login"
-d @login.txt
URI の Soap/u/ 部分は Partner WSDL を指定しています。これを Soap/c/ に変更
すると、Enterprise WSDL を指定できます。
4. Salesforce は、<sessionId> 要素と <serverUrl> 要素を含む XML 応答を返しま
す。<sessionId> 要素の値と、<serverUrl> 要素内のホスト名の最初にある
インスタンス (na1-api など) をメモしておいてください。これらの値は、後続
の処理で Bulk API に要求を送信するときに使用します。
ステップ 2: ジョブの作成
データを読み込むには、まずジョブを作成する必要があります。ジョブには、読み込
むオブジェクトの種別 (取引先責任者など) と、実行する処理 (クエリ、挿入、更新、
更新/挿入、削除など) を指定します。ジョブでは、ユーザがデータ読み込みのプロセ
スをある程度制御できます。たとえば、進行中のジョブを中止することなどが可能で
す。
cURL を使用してジョブを作成する手順は、次のとおりです。
1. job.txt という名前のテキストファイルを作成し、次のテキストを含めます。
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<operation>insert</operation>
<object>Contact</object>
<contentType>CSV</contentType>
</jobInfo>
139
第 9 章 Bulk API
警告: この operation 項目の値はすべて小文字で入力してください。たと
えば、insert の代わりに INSERT と入力すると、エラーが発生します。
2. コマンドラインウィンドウを使用して、次の cURL コマンドを実行します。
curl https://instance.salesforce.com/services/async/33.0/job
-H "X-SFDC-Session: sessionId" -H "Content-Type:
application/xml; charset=UTF-8" -d @job.txt
instance は、ログインの応答でメモした <serverUrl> 要素の一部分です。
sessionId は同様にメモした <sessionId> 要素です。
Salesforce により、次のようなデータを含む XML 応答が返されます。
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>750x0000000005LAAQ</id>
<operation>insert</operation>
<object>Contact</object>
<createdById>005x0000000wPWdAAM</createdById>
<createdDate>2009-09-01T16:42:46.000Z</createdDate>
<systemModstamp>2009-09-01T16:42:46.000Z</systemModstamp>
<state>Open</state>
<concurrencyMode>Parallel</concurrencyMode>
<contentType>CSV</contentType>
<numberBatchesQueued>0</numberBatchesQueued>
<numberBatchesInProgress>0</numberBatchesInProgress>
<numberBatchesCompleted>0</numberBatchesCompleted>
140
第 9 章 Bulk API
<numberBatchesFailed>0</numberBatchesFailed>
<numberBatchesTotal>0</numberBatchesTotal>
<numberRecordsProcessed>0</numberRecordsProcessed>
<numberRetries>0</numberRetries>
<apiVersion>33.0</apiVersion>
</jobInfo>
3. <id> 要素内に返されたジョブ ID の値をメモしておいてください。後続の処理
で使用します。
ステップ 3: ジョブへのバッチの追加
ジョブを作成したら、続いて、取引先責任者レコードのバッチを作成できます。デー
タをバッチにまとめ、複数の HTTP POST 要求で分割して送信します。各要求の URI は、
ジョブの作成で使用したものとよく似ていますが、今回は URI の末尾に jobId/batch
を追加します。
バイナリ型の添付ファイルを含めない場合は、データの形式を CSV か XML に設定しま
す。バイナリ型の添付ファイルについては、「バイナリ型の添付ファイルの読み込
み」を参照してください。バッチサイズの制限については、「バッチサイズ」を参照
してください。
この例では、推奨される形式である CSV を使用します。データセットは、バッチサイ
ズの制限内に収まるように適宜分割してください。ここでは、説明をわかりやすくす
るために少数のレコードのみを使用します。
ジョブにバッチを追加する手順は、次のとおりです。
1. data.csv という名前の CSV ファイルを作成し、次のような 2 件のレコードを
含めます。
FirstName,LastName,Department,Birthdate,Description
Tom,Jones,Marketing,1940-06-07Z,"Self-described as ""the top""
branding guru on the West Coast"
Ian,Dury,R&D,,"World-renowned expert in fuzzy logic design.
141
第 9 章 Bulk API
Influential in technology purchases."
最後の行の Description 項目の値は 2 行にわたっているため、二重引用符で
囲みます。
2. コマンドラインウィンドウを使用して、次の cURL コマンドを実行します。
curl
https://instance.salesforce.com/services/async/33.0/job/jobId/batch
-H "X-SFDC-Session: sessionId" -H "Content-Type: text/csv;
charset=UTF-8" --data-binary @data.csv
instance は、ログインの応答でメモした <serverUrl> 要素の一部分です。
sessionId は同様にメモした <sessionId> 要素です。jobId は、ジョブ作
成時に返されたジョブ ID です。
Salesforce により、次のようなデータを含む XML 応答が返されます。
<?xml version="1.0" encoding="UTF-8"?>
<batchInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>751x00000000079AAA</id>
<jobId>750x0000000005LAAQ</jobId>
<state>Queued</state>
<createdDate>2009-09-01T17:44:45.000Z</createdDate>
<systemModstamp>2009-09-01T17:44:45.000Z</systemModstamp>
<numberRecordsProcessed>0</numberRecordsProcessed>
</batchInfo>
Salesforce では CSV のコンテンツは解析しませんが、代わりに後続の処理でバッ
チが検証されます。この応答は単にバッチが受信されたことを知らせるための
ものです。
142
第 9 章 Bulk API
3. <id> 要素内で返されたバッチ ID の値をメモしておいてください。このバッチ
ID は、後でバッチの状況を確認するときに使用します。
ステップ 4: ジョブの終了
Salesforce へのバッチの送信が完了したら、ジョブを終了します。ジョブを終了する
と、このジョブのバッチはこれ以上送信されないことが Salesforce に通知され、監視
ページに、ジョブの処理状況に関する正確な統計データが表示されます。
cURL を使用してジョブを終了する手順は、次のとおりです。
1. close_job.txt という名前のテキストファイルを作成し、次のテキストを含
めます。
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<state>Closed</state>
</jobInfo>
2. コマンドラインウィンドウを使用して、次の cURL コマンドを実行します。
curl
https://instance.salesforce.com/services/async/33.0/job/jobId
-H "X-SFDC-Session: sessionId" -H "Content-Type:
application/xml; charset=UTF-8" -d @close_job.txt
instance は、ログインの応答でメモした <serverUrl> 要素の一部分です。
sessionId は同様にメモした <sessionId> 要素です。jobId は、ジョブ作
成時に返されたジョブ ID です。
この cURL コマンドは、ジョブリソースの状況を Open から Closed に更新しま
す。
ステップ 5: バッチの状況の確認
次の cURL コマンドを実行すると、個々のバッチの状況を確認できます。
143
第 9 章 Bulk API
curl
https://instance.salesforce.com/services/async/33.0/job/jobId/batch/batchId
-H "X-SFDC-Session: sessionId"
instance は、ログインの応答でメモした <serverUrl> 要素の一部分です。
sessionId は同様にメモした <sessionId> 要素です。jobId は、ジョブ作成時に
返されたジョブ ID です。batchId は、ジョブにバッチを追加したときに返されたバッ
チ ID です。
Salesforce により、次のようなデータを含む XML 応答が返されます。
<?xml version="1.0" encoding="UTF-8"?>
<batchInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>751x00000000079AAA</id>
<jobId>750x0000000005LAAQ</jobId>
<state>Completed</state>
<createdDate>2009-09-01T17:44:45.000Z</createdDate>
<systemModstamp>2009-09-01T17:44:45.000Z</systemModstamp>
<numberRecordsProcessed>2</numberRecordsProcessed>
</batchInfo>
Salesforce でバッチのコンテンツを読み取れなかった場合や、バッチにエラーが含まれ
ていた場合 (例: CSV ファイルのヘッダー行に無効な項目名が含まれていた場合など)、
バッチの状態は Failed になります。バッチ内のすべてのレコードが処理されると、
バッチの状態は Completed になります。ただし、バッチの中には処理に失敗したレ
コードが含まれている場合があります。個々のレコードの状況を確認するために、
バッチ結果を取得する必要があります。
各バッチの状況を個別に確認する必要はありません。次の cURL コマンドを実行する
と、ジョブに含まれているすべてのバッチの状況を確認できます。
144
第 9 章 Bulk API
curl
https://instance.salesforce.com/services/async/33.0/job/jobId/batch
-H "X-SFDC-Session: sessionId"
ステップ 6: バッチ結果の取得
単一のバッチを実行して、その状況が Completed と表示されたら、そのバッチ結果
を取得して個々のレコードの状況を確認する必要があります。
単一のバッチの結果を取得するには、次の cURL コマンドを実行します。
curl
https://instance.salesforce.com/services/async/33.0/job/jobId/batch/batchId/result
-H "X-SFDC-Session: sessionId"
instance は、ログインの応答でメモした <serverUrl> 要素の一部分です。
sessionId は同様にメモした <sessionId> 要素です。jobId は、ジョブ作成時に
返されたジョブ ID です。batchId は、ジョブにバッチを追加したときに返されたバッ
チ ID です。
Salesforce により、次のようなデータを含む応答が返されます。
"Id","Success","Created","Error"
"003x0000004ouM4AAI","true","true",""
"003x0000004ouM5AAI","true","true",""
レスポンスボディは、バッチ要求の各行に対応する行が含まれた CSV ファイルです。
レコードが作成されると、行に ID が挿入されます。レコードが更新されると、Created
列の値が「false」になります。レコードの処理が失敗すると、Error 列にエラーメッ
セージが挿入されます。
ベストプラクティス
このセクションで説明するベストプラクティスを考慮してください。
145
第 9 章 Bulk API
データ読み込みに関する一般的なガイドライン
このセクションでは、最小限の処理時間でデータ読み込みが実行されるように計画を
立てるためのヒントを紹介します。データ読み込みを行う場合は、事前に必ず Sandbox
組織でテストを実行します。ただし、Sandbox 組織と本番組織とでは、処理時間が異
なる可能性があります。
できる限り並列モードを使用する
バッチを並列モードで処理することにより、Bulk API のメリットを最大限に引き出
すことができます。並列モードはデフォルトで選択されており、より迅速なデー
タ読み込みを可能にします。ただし、並列モードを使用すると、レコードに対す
るロック競合が発生することがあります。これを回避するには、逐次モードを使
用して処理を実行します。ただし、並列モードだとロックタイムアウトが発生し、
バッチを再構成してもロックを回避できないとわかっている場合以外は、逐次モー
ドでデータ処理を実行しないでください。
処理モードはジョブレベルで設定します。1 つのジョブに含まれるすべてのバッチ
が並列モード、逐次モードのいずれかで処理されます。
ロック競合を回避できるようにバッチを再構成する
たとえば、AccountTeamMember レコードの作成や更新を行う場合、このレコードが
参照する取引先レコードは、トランザクションが完了するまでロックされます。
AccountTeamMember レコードのバッチを複数読み込む場合に、これらのレコードに
同一の取引先への参照が含まれていると、すべてのバッチで同じ取引先をロック
しようとするため、ロックタイムアウトが発生することが予想されます。このよ
うな場合、バッチへのデータの振り分けを見直すことで、ロックタイムアウトを
回避できる可能性があります。たとえば、AccountId 別に AccountTeamMember レ
コードを分類して、同じ取引先を参照するすべてのレコードを 1 つのバッチにまと
めると、複数のバッチによるロック競合のリスクを減らすことができます。
Bulk APIでは、ロックが発生するとただちにエラーが返されるわけではありません。
ロックが解除されるのを数秒間待ち、解除されない場合はレコードを Failed として
マークします。1 つのバッチ内で、100 を超えるレコードに対してロックが確認さ
れた場合、そのバッチの未処理のリクエストはいったんキューに戻されます。後
で再度同じバッチが処理されるとき、Failed としてマークされたレコードは再試行
されません。これらのレコードを処理するには、別のバッチにまとめて再送信す
る必要があります。
再度の処理も正常に完了しなかった場合、バッチは再びキューに戻され、最大 10
回まで処理が試行されます。それでも完了できない場合は、バッチ処理が完全に
146
第 9 章 Bulk API
失敗したとみなされます。バッチの状態が Failed であっても、一部のレコードは正
常に処理されている可能性があります。バッチ結果を取得して、個々のレコード
の処理状況を確認する方法については、「バッチ結果の取得」を参照してくださ
い。エラーが回避されない場合は、別のジョブを作成し、データを逐次モードで
処理します。逐次モードでは、バッチが 1 つずつ順番に処理されます。
ロック競合を引き起こしやすい処理に注意する
次に示すのは、ロック競合を引き起こしやすい処理です。これらの処理では必要
に応じて逐次モードを使用します。
• 新規ユーザの作成
• 非公開で共有されているレコードの所有者の更新
• ユーザロールの更新
• テリトリー階層の更新
これらの処理に関連するエラーが発生した場合は、別のジョブを作成し、逐次モー
ドでデータを処理してください。
メモ: データモデルは組織ごとに異なるため、ロック競合が発生する条件は、
上記で説明したものと一致しない場合があります。
項目の数を最小限に抑える
各レコードの読み込む項目数が少ないほど、処理時間は短くなります。外部キー
項目、参照関係項目、積み上げ集計項目が含まれると、処理時間が長くなる傾向
にあります。項目の数を減らすことが難しい場合もあるかと思いますが、可能で
あれば実行してください。これにより、読み込み時間を短縮できます。
ワークフローアクションの数を最小限に抑える
ワークフローアクションの数が増えると処理時間が長くなります。
トリガの数を最小限に抑える
トリガが関連付けられたオブジェクトでは、それらのトリガが他の並列トランザ
クションに悪影響を及ぼさないようであれば、並列モードを使用してもかまいま
せん。ただし、Salesforce では、複雑なトリガが関連付けられたオブジェクトを含
む、サイズの大きなバッチを読み込むことは推奨していません。代わりに、すべ
てのデータが読み込まれた後に実行される一括処理 Apex ジョブとして、トリガの
ロジックを記述し直すことをお勧めします。
バッチサイズを最適化する
Salesforceでは、すべての顧客組織間で処理リソースが共有されます。各組織がバッ
チの処理を長時間待たなくても済むように、処理に 10 分以上かかるバッチはいっ
147
第 9 章 Bulk API
たんキューに戻され、後で処理されます。そのため、処理時間を短縮する最善の
方法は、10 分以内に処理が完了するバッチを送信することです。一括処理のタイ
ミングの監視についての詳細は、「バッチの監視」を参照してください。
バッチサイズは処理時間に基づいて調整する必要があります。まず 5,000 件のレ
コードを含むバッチで処理を試行し、処理時間に応じてサイズを調整します。1 つ
のバッチの処理に 5 分以上かかるようなら、バッチサイズを小さくしたほうがよい
でしょう。数秒で完了するようであれば、バッチサイズを大きくします。バッチ
の処理時にタイムアウトエラーが発生する場合は、バッチをより小さなサイズに
分割して再試行します。詳細は、「Bulk API の制限」を参照してください。
メモ: 一括クエリの場合、バッチサイズはクエリ結果セットと取得データサ
イズのどちらにも適用されません。一括クエリの処理に時間がかかりすぎる
場合、クエリステートメントを絞り込んで、返されるデータ量を減らす必要
があります。
レスポンスの圧縮の使用
API バージョン 27.0 以降では、Bulk API は、レスポンスデータを圧縮することができま
す。これにより、ネットワークのトラフィックが削減され、応答時間が短縮されま
す。
レスポンスは、クライアントが gzip の値を持つ Accept-Encoding ヘッダーを使用
して要求を行う場合に圧縮されます。Bulk API はレスポンスを gzip 形式で圧縮し、
Content-Encoding: gzip 応答ヘッダーを持つクライアントにレスポンスを送信し
ます。gzip 以外の値を持つ Accept-Encoding ヘッダーを使用して要求が行われる
と、エンコードタイプは無視され、レスポンスは圧縮されません。
たとえば、Accept-Encoding: gzip ヘッダーを使用してBatch Results 要求が行われた
場合、レスポンスは次のようになります。
HTTP/1.1 200 OK
Date: Tue, 09 Oct 2012 18:36:45 GMT
Content-Type: text/csv; charset=UTF-8
Content-Encoding: gzip
Transfer-Encoding: chunked
148
第 9 章 Bulk API
...compressed response body...
Bulk API は、レスポンスの圧縮の HTTP 1.1 標準に従います。ほとんどのクライアントは
圧縮レスポンスを自動的にサポートします。クライアント別の詳細は、
https://developer.salesforce.com/page/Tools を参照してください。
リソース
Bulk API に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• Bulk API 開発者ガイド
• Salesforce オブジェクトリファレンス
• API とインテグレーションに関するフォーラム
149
第 10 章
ストリーミング API
ストリーミング API を使用すると、定義したデータクエリに一致する Salesforce データ
への変更があった場合に、安全で拡張性の高い方法で通知を受け取ることができま
す。
ストリーミング API を使用するケース
ストリーミング API は、サーバからクライアントに通知を転送する必要がある場合に
役立ちます。頻繁にポーリングを行うアプリケーションではストリーミング API を検
討してください。Salesforce インフラストラクチャに対して常時ポーリングアクション
を行い、不要な API コールや処理時間を消費するアプリケーションでは、データを返
さない要求数を削減する、この API にメリットがあります。また、ストリーミング API
はデータ変更の一般的な通知を要求するアプリケーションに最適です。これにより、
API コールの数を削減し、パフォーマンスを改善することができます。
ストリーミング API イベントは次の場所で受信できます。
• Salesforce アプリケーション内のページ。
• Salesforce 外のアプリケーションサーバ。
• Salesforce アプリケーション外のクライアント。
ストリーミング API は、転送技術を使用して通知イベントをクライアントに送信しま
す。転送技術では、クライアントが情報のチャネルに登録すると、サーバがクライア
ントに情報を転送します。クライアントが情報を受け取るには、サーバへの接続を維
持する必要があります。ストリーミング API は Bayeux プロトコルと CometD を使用する
ため、クライアントからサーバへの接続は long polling を使用して維持されます。
サポート対象のエディションとプラットフォーム
ストリーミング API を使用するには、組織で Enterprise Edition、Performance Edition、Unlimited
Edition、または Developer Edition を使用している必要があります。既存の Salesforce のお
151
第 10 章 ストリーミング API
客様が Enterprise Edition、Unlimited Edition、または Performance Edition にアップグレードす
る場合は、担当者にご連絡ください。
ストリーミング API の場合、[設定] の [カスタマイズ] > [ユーザインターフェース] で、
「ストリーミング API」権限と「API の有効化」権限が組織で有効であることを確認す
る必要があります。
ワークベンチを使用したクイックスタート
このクリックスタートでは、ワークベンチを使って、ストリーミング API の使用を開
始する方法を説明します。レコードが更新されたときにストリーミング API を使用し
て通知を受け取るプロセスをステップごとに説明します。
• 前提条件
• ステップ 1: オブジェクトを作成する
• ステップ 2: PushTopic を作成する
• ステップ 3: PushTopic チャネルに登録する
• ステップ 4: PushTopic チャネルをテストする
前提条件
クイックスタートの手順を実行するには、アクセス権と適切な権限が必要です。
• Developer Edition 組織にアクセスします。
まだ Force.com 開発者コミュニティのメンバーでない場合、
developer.salesforce.com/signup にアクセスし、Developer Edition 組織のサイ
ンアップの説明に従ってください。すでに Enterprise Edition、Unlimited Edition、また
は Performance Edition を所有している場合でも、組織の使用中のデータを保護するた
めに、サンプルデータに対するソリューションの開発、ステージングおよびテス
トには Developer Edition を使用します。これは、特に、(データをただ参照するだけ
のアプリケーションに対し) データを挿入、更新または削除するアプリケーション
の場合に該当します。
• Developer Edition 組織で「API の有効化」権限を有効にする必要があります。この権
限はデフォルトで有効になっていますが、システム管理者によって変更されてい
る場合があります。
152
第 10 章 ストリーミング API
• 「ストリーミング API」権限を有効にする必要があります。
メモ: 組織で「API の有効化」権限と「ストリーミング API」権限が有効である
ことを確認するには、[設定] から [カスタマイズ] > [ユーザインターフェース]
をクリックします。
• ログインユーザが通知を受信するには、PushTopic 標準オブジェクトに対する「参
照」権限が必要です。
• ログインユーザが PushTopic レコードを作成および管理するには、PushTopic 標準オ
ブジェクトに対する「作成」権限が必要です。
• ログインユーザが開発者コンソールを使用して PushTopic を作成するには、「Apex
開発」権限が必要です。
ステップ 1: オブジェクトを作成する
最初のステップでは、InvoiceStatement (請求書明細) オブジェクトを作成します。PushTopic
を作成し、その PushTopic に登録すると、InvoiceStatement レコードが作成、更新、削除、
復元されたときに通知を受け取れます。オブジェクトは Salesforce ユーザインターフェー
スで作成します。
1. [設定] から、[作成] > [オブジェクト] をクリックします。
2. [新規カスタムオブジェクト] をクリックし、カスタムオブジェクト定義を入力
します。
• [表示ラベル] 項目に「Invoice Statement」と入力します。
• [表示ラベル(複数形)] 項目に「Invoice Statements」と入力します。
• [母音で始まる場合はチェック] を選択します。
• [レコード名] 項目に「Invoice Number」と入力します。
• [データ型] 項目で、[自動採番] を選択します。
• [表示形式] 項目に「INV-{0000}」と入力します。
• [開始番号] 項目に「1」と入力します。
3. [保存] をクリックします。
4. [Status] 項目を追加します。
a. [カスタム項目 & リレーション] 関連リストまで下方向へスクロールして [新
規] をクリックします。
153
第 10 章 ストリーミング API
b. [データ型] で [選択リスト] を選択し、[次へ] をクリックします。
c. [表示ラベル] 項目に「Status」と入力します。
d. 表示されたボックスに、1 行に 1 エントリずつ次の選択リスト値を入力しま
す。
Open
Closed
Negotiating
Pending
e. [最初の値をデフォルト値とする] のチェックボックスをオンにします。
f. [次へ] をクリックします。
g. 項目レベルセキュリティで、[参照のみ] を選択し、[次へ] をクリックしま
す。
h. [保存 & 新規] をクリックして、この項目を保存し、新しい項目を作成しま
す。
5. 次に、[Description] 項目を作成します (省略可能)。
a. [データ型] 項目で [テキストエリア] を選択し、[次へ] をクリックします。
b. [項目の表示ラベル] 項目と [項目名] 項目に、「Description」と入力しま
す。
c. [次へ] をクリックし、デフォルトを受け入れて、[次へ] をもう一度クリック
します。
d. [保存] をクリックして InvoiceStatement オブジェクトの詳細ページに移動しま
す。
これで InvoiceStatement オブジェクトに 2 つのカスタム項目が作成されました。
154
第 10 章 ストリーミング API
ステップ 2: PushTopic を作成する
開発者コンソールを使用してSOQLクエリが含まれる PushTopic レコードを作成します。
イベント通知は、クエリに一致する更新について生成されます。または、ワークベン
チを使用して PushTopic を作成することもできます。
1. あなたの名前 > [開発者コンソール] を選択します。
2. [Debug (デバッグ)] > [Open Execute Anonymous Window (実行匿名ウィンドウを開
く)] をクリックします。
3. [Enter Apex Code (Apex コードを入力)] ウィンドウに次の Apex コードを貼り付けて、
[Execute (実行)] をクリックします。
PushTopic pushTopic = new PushTopic();
pushTopic.Name = 'InvoiceStatementUpdates';
pushTopic.Query = 'SELECT Id, Name, Status__c, Description__c
FROM Invoice_Statement__c';
pushTopic.ApiVersion = 33.0;
pushTopic.NotifyForOperationCreate = true;
pushTopic.NotifyForOperationUpdate = true;
pushTopic.NotifyForOperationUndelete = true;
pushTopic.NotifyForOperationDelete = true;
pushTopic.NotifyForFields = 'Referenced';
insert pushTopic;
メモ: 組織で名前空間プレフィックスが定義済みの場合は、PushTopic ク
エリを定義するときにカスタムオブジェクトおよび項目の名前の先頭に
名前空間を指定する必要があります。たとえば、SELECT Id, Name,
namespace__Status__c, namespace__Description__c FROM
namespace__Invoice_Statement__c と指定します。
NotifyForOperationCreate、NotifyForOperationUpdate、
NotifyForOperationDelete、NotifyForOperationUndelete は true に
155
第 10 章 ストリーミング API
設定されているため、ストリーミング API は作成、更新、削除、復元されたレ
コードを評価し、レコードが PushTopic クエリに一致する場合は通知を生成しま
す。NotifyForFields は Referenced に設定されているため、ストリーミン
グ API は SELECT 句と WHERE 句の両方の項目を使用して通知を生成します。項目
Name、Status__c、または Description__c が更新されると常に、通知がこ
のチャネル上に生成されます。NotifyForOperationCreate、
NotifyForOperationUpdate、NotifyForOperationDelete、
NotifyForOperationUndelete、NotifyForFields についての詳細は、「イ
ベント通知ルール」を参照してください。
メモ: API バージョン 28.0 以前では、レコードが作成または更新されたと
きにのみ通知が生成されます。NotifyForOperationCreate、
NotifyForOperationUpdate、NotifyForOperationDelete、
NotifyForOperationUndelete 項目は使用できず、通知を生成するレ
コードイベントの設定には NotifyForOperations 列挙項目が代わりに
使用されます。詳細は、「PushTopic」を参照してください。
ステップ 3: PushTopic チャネルに登録する
このステップでは、前のステップで PushTopic レコードを使用して作成したチャネルに
登録します。
重要: ワークベンチは、無料のオープンソースのコミュニティサポートツールで
す (ワークベンチのヘルプページを参照)。Salesforce は、デモ目的でのみワークベ
ンチのホスト型インスタンスを提供しています。このワークベンチのホスト型イ
ンスタンスを本番データベースのデータへのアクセスに使用することはお勧めし
ません。ワークベンチを本番データベースに使用する場合は、各自で所有するリ
ソースを使用してワークベンチをダウンロード、ホスト、および設定してくださ
い。
ワークベンチは、http://code.google.com/p/forceworkbench/downloads/list からダウンロー
ドできます。
1. ブラウザで、https://developer.salesforce.com/page/Workbench に移
動します。
2. [Environment (環境)] で [Production (本番)] を選択します。
3. [API Version (API バージョン)] で 33.0 を選択します。
156
第 10 章 ストリーミング API
4. サービスの利用規約に同意し、[Login with Salesforce (Salesforce でログイン)] をク
リックします。
5. データベースへの接続が確立されると、[Select (選択)] ページが表示されます。
6. [queries (クエリ)] > [Streaming Push Topics (ストリーミング転送トピック)] をク
リックします。
7. [Push Topic (転送トピック)] 項目で [InvoiceStatementUpdates] を選択します。
8. [Subscribe (登録)] をクリックします。
接続および応答情報と "Subscribed to /topic/InvoiceStatementUpdates" のような応答が
表示されます。
このブラウザウィンドウを開いたままにして、接続がタイムアウトしないようにしま
す。次のステップでは、作成した InvoiceStatement レコードがトリガしたイベント通知
を表示できます。
ステップ 4: PushTopic チャネルをテストする
ステップ 3: PushTopic チャネルに登録するで使用したブラウザが開いたままで、接続が
タイムアウトしていないことを確認します。このブラウザでイベント通知を表示しま
す。
最後のステップとして PushTopic チャネルをテストするために、ワークベンチで新しい
InvoiceStatement レコードを作成し、イベント通知を表示します。
1. 新しいブラウザウィンドウで、ワークベンチのインスタンスを開き、ステップ
3: PushTopic チャネルに登録するで使用した手順に従い、同じユーザ名を使用し
てログインします。
メモ: レコードを更新したユーザとチャネルに登録したユーザがレコー
ドを共有していない場合、登録したユーザは通知を受け取りません。た
とえば、組織の共有モデルが非公開の場合などです。
2. [data (データ)] > [Insert (挿入)] をクリックします。
3. [Object Type (オブジェクト種別)] で、[Invoice_Statement__c] を選択します。[Single
Record (単一レコード)] 項目が選択されていることを確認し、[Next (次へ)] をク
リックします。
4. [Description__c] 項目に値を入力します。
157
第 10 章 ストリーミング API
5. [Confirm Insert (挿入を確認)] をクリックします。
6. [Streaming Push Topics (ストリーミング転送トピック)] ブラウザウィンドウに切り
替えます。InvoiceStatement レコードが作成されたという通知が表示されます。
通知では、PushTopic クエリの SELECT ステートメントで定義した Id、Status__c、
および Description__c 項目が返されます。メッセージは次のようになりま
す。
{
"channel": "/topic/InvoiceStatementUpdates",
"data": {
"event": {
"type": "created",
"createdDate": "2011-11-14T17:33:45.000+0000"
},
"sobject": {
"Name": "INV-0004",
"Id": "a00D0000008oLi8IAE",
"Description__c": "Test invoice statement",
"Status__c": "Open"
}
}
}
ベストプラクティス
このセクションで説明するベストプラクティスを考慮してください。
158
第 10 章 ストリーミング API
クライアントとタイムアウト
ストリーミング API では、Bayeux プロトコルでサポートされている 2 つのタイムアウト
が適用されます。
ソケットタイムアウト: 110 秒
クライアントは、接続の待機中にイベント (JSON 形式の HTTP 応答) を受信します。
イベントが生成されずにクライアントが引き続き待機している場合、接続は110 秒
後にタイムアウトし、サーバは接続を閉じます。クライアントは、2 分以内に再接
続して接続タイムアウトを回避する必要があります。
再接続タイムアウト: 40 秒
イベントを受信したら、クライアントは次のイベントのセットを受け取るために
再接続する必要があります。40 秒以内に再接続しないと、サーバが登録を期限切
れにし、接続が終了します。この状態が発生すると、クライアントはハンドシェ
イク、登録、および接続を最初から再度やり直す必要があります。
各ストリーミング API クライアントは、インスタンスにログインし、セッションを維
持します。クライアントがハンドシェイク、接続、または登録を行うと、セッション
タイムアウトが再び最初から適用されます。クライアントが応答 (イベント、登録結
果など) を受信してから 40 秒以内にサーバに再接続しない場合、クライアントセッショ
ンはタイムアウトします。
そのセッションにアクティビティがない場合、組織のタイムアウトが適用されて、
セッションが終了します。
ストリーミング API のクライアントと Cookie
ストリーミング API を使用するために作成したクライアントは、サーバとの間で使用
される標準 Cookie プロトコルに従う必要があります。クライアントは、
https://instance_name.salesforce.com/cometd など、ドメインおよび URI パ
スに対応した適切な Cookie を受け取って送信する必要があります。
クライアントに対する ストリーミング API 要件は次のとおりです。
• POST のコンテンツが JSON の場合、cometd へのすべてのコールに "Content-Type:
application/json" ヘッダーが必要です。
• Salesforce セッション ID または OAuth トークンを含むヘッダーが必要です。たとえ
ば、Authorization: Bearer sessionId と指定します。
159
第 10 章 ストリーミング API
• クライアントは、ドメインおよび URI パスに対応した適切な Cookie をすべて受け
取って返送する必要があります。クライアントは、サーバとの間で使用される標
準 Cookie プロトコルに従う必要があります。
• 登録応答とその他の応答には、次の項目が含まれている場合があります。これら
の項目は、CometD 仕様には含まれません。
– EventType に created または updated のいずれかが含まれる。
– CreatedDate にイベントの作成日が含まれる。
サポートされるブラウザ
ストリーミング API では、次のブラウザがサポートされます。
• Internet Explorer 8 以上
• Firefox 4 以上
最新のセキュリティ更新と修正が適用された最新バージョンのブラウザを使用するこ
とをお勧めします。Internet Explorer 6 または 7 を使用する必要がある地域では、jQuery
1.5.1 および CometD 2.2.0 を使用する Streaming API でこれらのブラウザが動作することが
Salesforce で確認済みです。
HTTPS の推奨
ストリーミング APIはシステム管理者が組織について定義した設定に従います。デフォ
ルトでは、これは HTTPS です。データのセキュリティを保護するために、HTTPS を使用
することをお勧めします。
ストリーミング API アプリケーションのデバッグ
ストリーミング API アプリケーションをデバッグするには、すべての要求と応答を確
認できる必要があります。ストリーミング API アプリケーションはステートフルであ
るため、アプリケーションのデバッグにはプロキシツールを使用する必要がありま
す。Burp Proxy、Fiddler、Firebugなど、すべての要求と結果の内容をレポートできるツー
ルを使用してください。
最も一般的なエラーとして次のようなものがあります。
• ブラウザと JavaScript の問題
160
第 10 章 ストリーミング API
• 正しくない順序で送信された要求
• Bayeux プロトコルに従っていない不正な形式の要求
• 認証の問題
• 長命 (long-lived) 接続によるネットワークまたはファイアウォールの問題
これらのツールを使用すると、要求、ヘッダー、post の本文、結果を参照できます。
Salesforce にお問い合わせいただくときは、トラブルシューティングに役立つようにこ
れらの要素をコピーして保存しておいてください。
デバッグプロセスの最初のステップでは、「ワークベンチを使用したクイックスター
ト」、「例: 対話型 Visualforce ページ」、「例: Visualforce ページ」、または「例: Java ク
ライアント」の手順に従って、提供されたサンプルを実装できることを確認します。
次のステップでは、デバッグツールを使用して、症状と問題の原因を切り分けます。
402 エラー
場合によっては、次のような「402::Uknown client」が含まれたエラー通知を受け取る場
合があります。
Thu Mar 29 06:08:08 PDT 2012 [CHANNEL:META_CONNECT]:
{"id":"78","error":"402::Unknown
client","successful":false,"advice":{"interval":500,"reconnect":"handshake"}
これは、クライアント接続のタイムアウトなど、さまざまな状況で発生します。この
エラーが発生した場合、サーバとハンドシェイクをして再接続する必要があります。
クライアントのタイムアウトとストリーミング API 制限についての詳細は、
「クライアントとタイムアウト」と「ストリーミング API の制限」を参照してくださ
い。
イベント使用状況の監視
24 時間の間に生成できるイベントの数は、組織の種別に応じて異なります。詳細は、
「ストリーミング API の制限」を参照してください。[組織情報] ページでストリーミ
ング API イベントの使用状況を監視できます。このページには以下の手順でアクセス
します。
• [設定] から、[組織プロファイル] > [組織情報] をクリックします。
161
第 10 章 ストリーミング API
[組織情報] ページを更新すると、ストリーミング API イベント値がわずかに変動する
場合があります。これらのわずかな変動に関係なく、設定した制限は正確に評価され
ます。
通知メッセージの順序
組織でのデータの変更は、順番に行われます。ただし、ストリーミング API でイベン
ト通知メッセージを受信する順序は保証されません。クライアント側では、
createdDate を使用して、チャネルに返される通知メッセージの順序を指定できま
す。createdDate の値は、イベントの発生時期を示す UTC 日付/時間の値です。
次のコードでは、複数のメッセージが生成されます。1 つはレコードの作成時に、も
う 1つはレコードの更新時に生成されます。
{
"channel": "/topic/InvoiceStatementUpdates",
"clientId": "1g177wgjj14omtdo3rcl0hjhm4w",
"data": {
"event": {
"type": "updated",
"createdDate": "2013-05-10T18:16:19.000+0000"
},
"sobject": {
"Name": "INV-0002",
"test_ds__Status__c": "Negotiating",
"test_ds__Description__c": "Update to invoice statement #2",
"Id": "a00D0000008pvxcIAA"
}
162
第 10 章 ストリーミング API
}
}
{
"channel": "/topic/InvoiceStatementUpdates",
"clientId": "1g177wgjj14omtdo3rcl0hjhm4w",
"data": {
"event": {
"type": "created",
"createdDate": "2013-05-10T18:15:11.000+0000"
},
"sobject": {
"Name": "INV-0003",
"test_ds__Status__c": "Open",
"test_ds__Description__c": "New invoice statement #1",
"Id": "a00D0000008pvzdIAA"
}
}
}
リソース
ストリーミング API に関する次のリソースについては、Salesforce 開発者のネットワー
ク (http://developer.salesforce.com/docs) を検索してください。
163
第 10 章 ストリーミング API
• ストリーミング API 開発者ガイド
• SOQL および SOSL リファレンスガイド
• API とインテグレーションに関するフォーラム
164
第 11 章
Data.com API
『Data.com API 開発者ガイド』には、Data.com 検索 API、Data.com 照合 API、Data.com ソー
シャルプロファイルマッチング API、Data.com 購入 API、Data.com DUNSRight マッチング
API、および Data.com レコード購入プロセスが含まれます。
Data.com 検索 API
Data.comデータベースで取引先責任者と企業を検索し、指定された項目の情報を返
す SOQL ベースのインターフェースです。この API は、Data.com プロスペクタを購入
した場合に使用できます。
Data.com 照合 API
取引先責任者と会社情報を最新のData.comデータと照合するためのマッチングサー
ビス (またはアルゴリズム) が備えられている REST ベースの API です。照合 API は、
Data.com フルクリーンアップを購入した場合に使用できます。
Data.com 購入 API
Data.com 購入 API を使用して、Data.com 企業および取引先責任者レコードを購入し
ます。1 つの POST 要求で複数の取引先責任者レコードを購入します。購入利用状
況情報、取引先責任者と企業の詳細、および購入の詳細情報も取得できます。
Data.com ソーシャルプロファイルマッチング API
Data.com 取引先責任者を LinkedIn や Twitter などのソーシャルハンドルとマッチング
します。
Data.com DUNSRight マッチング API:
DUNS 番号やその他のキー項目によって、企業をマッチングします。Data.com DUNSRight
マッチング API は、統合されたマッチング API コールパターンを使用します。マッ
チングオプションを URL ではなく POST ボディに指定できるようになりました。
Data.com のレコード購入プロセスフロー
Data.com のレコード購入プロセスについての簡単な概要です。
165
第 11 章 Data.com API
Data.com API を使用するケース
Data.com 購入 API は、1 つの API コールで取引先責任者または企業を購入するための接
続スタイルの API を提供します。
Data.com プロスペクタおよび Data.com クリーンアップでは、標準で Data.com による高
度な検索およびマッチング機能を利用できます。Data.com 検索 API と Data.com 照合 API
は、Data.com プロスペクタおよびData.com クリーンアップで提供されない機能を拡張
するために使用します。Data.com API では、Salesforce を操作するための強力で便利な使
いやすいインターフェースを提供します。
最新の Data.com API についての説明は、「はじめに」を参照してください。
サポート対象のエディションとプラットフォーム
Data.com API を使用するには、組織で Enterprise Edition、Performance Edition、または Developer
Edition を使用している必要があります。組織でData.com検索 API を使用するにはData.com
プロスペクタも購入する必要があり、Data.com 照合 API、Data.com ソーシャルプロファ
イルマッチング API、または Data.com DUNSRight マッチング API を使用するには Data.com
クリーンアップも購入する必要があります。使用している Salesforce エディションを
アップグレードする場合、または Data.com プロスペクタまたはData.com クリーンアッ
プを購入する場合は、営業担当者にお問い合わせください。
最新のすべての Data.com API についての詳細は、『Data.com API Deverloper’s Guide』を参照
してください。
Data.com 検索 API
Data.com 検索 API は、Data.com データベースで取引先責任
者や会社を検索するために Datacloud オブジェクトと共
に使用します。検索は、クエリ内の条件に基づき、指
定された項目に関する情報を返します。
実行可能な API コール数は 24 時間単位で割り当てられま
す。組織は、購入済みのData.com プロスぺクタライセン
スごとに 1 日あたり 1,000 コールを実行できます。たと
えば、10 個のプロスペクタライセンスを有する組織で
166
エディション
使用可能なエディション:
Developer Edition、
Professional Edition (アドオ
ン)、Enterprise Edition、お
よび Performance Edition
第 11 章 Data.com API
は、検索 API コールが 1 日あたり 10,000 回 (1,000 x 10 = 10,000) に制限されます。コール割
り当ては、Salesforce 組織レベルで実装されます。
組織のユーザインターフェースから、API コールの制限を表示できます。
1. [設定] から、[Data.com 管理] > [ライセンスと制限] をクリックします。
2. [Data.com API] セクションで、[Data.com API 制限 (1 日あたり)] を表示します。
最新のすべての Data.com API についての詳細は、『Data.com API Deverloper’s Guide』を参照
してください。
Data.com 照合 API
Data.com 照合 API には、取引先責任者と会社情報を最新
のData.comデータと照合するためのマッチングサービス
(またはアルゴリズム) が備えられています。API では、
ユーザのレコードと Data.com レコードを照合して、レ
コードがどのように異なるかが示されます。
Data.com 照合のための REST API には、次の 2 つのリソー
スがあります。
エディション
使用可能なエディション:
Developer Edition、
Professional Edition (アドオ
ン)、Enterprise Edition、お
よび Performance Edition
• DatacloudContact: Data.com データベースの取引先責任
者から一致するデータを返します。
• DatacloudCompany: Data.com の会社から一致するデータを返します。
ユーザのデータを Data.com のレコードと照合するには、POST 要求を使用します。
実行できる API コール数に対して、24 時間のローリング時間が割り当てられます。組
織は、購入済みのライセンスごとに 1 日あたり 1,000 コールを行うことができます。た
とえば、10 個のクリーンアップライセンスを持つ組織では、照合 API コールは 1 日あ
たり 10,000 回 (1,000 x 10 = 10,000) に制限されます。コール割り当ては、Salesforce 組織レ
ベルで実装されます。
最新のすべての Data.com API についての詳細は、『Data.com API Deverloper’s Guide』を参照
してください。
167
第 11 章 Data.com API
Data.com 購入 API
Data.com 購入 API を使用して、Data.com 企業および取引先責任者レコードを購入しま
す。
Chatter REST API の一部である Data.com 購入 API は、Data.com の取引先責任者および会社
レコードの購入、レコード詳細の取得、特定の注文に関する購入の詳細の取得に使用
されます。
Data.com DUNSRight マッチング API:
Data.com DUNSRight マッチング API は、DUNSRight マッチングエンジンによって、取引先
レコードをData.com企業レコードとマッチングするために使用します。DUNS 番号やそ
の他のキー項目によって、マッチングできます。
Data.com DUNSRight マッチング API は、統合されたマッチング API コールパターンを使用
します。マッチングオプションを URL ではなく POST ボディに指定できるようになりま
した。
メモ: Data.com DUNSRight マッチング API のすべての例は、読みやすくするために
書式設定されています。
Data.com ソーシャルプロファイルマッチング API
Data.com 取引先責任者を LinkedIn や Twitter などのソーシャルハンドルとマッチングしま
す。
Data.com ソーシャルプロファイルマッチング API は、統合されたマッチング API コール
パターンを使用します。マッチングオプションを URL ではなく POST ボディに指定でき
るようになりました。
Data.com レコードの購入
Data.com API を使用して、取引先責任者レコードまたは会社レコードを Data.com から購
入できます。レコードを購入すると、そのレコードのすべてのData.com情報に Salesforce
内のどこからでもアクセスできます。
168
第 11 章 Data.com API
最新のすべての Data.com API についての詳細は、『Data.com API Deverloper’s Guide』を参照
してください。
169
第 12 章
SOQL と SOSL
Salesforce Object Query Language (SOQL) と Salesforce Object Search Language (SOSL) はそれぞれ、
他の多くの Salesforce API 内で使用されるデータクエリ言語とデータ検索言語です。
SOQL を使用するケース
強力なデータクエリ文字列を作成する必要がある場合は常にSOQLを使用します。SOQL
は、直接は使用されず、他の Salesforce API 環境を介して使用されます。SOQL の使用例
として次のようなものがあります。
• query() および queryAll() SOAP API コール内の queryString パラメータ。
• REST API の query および queryAll リソースで使用されるクエリ要求パラメータ。
• Bulk API の一括クエリ要求のクエリ部分。
• ストリーミング API チャネルの基本を定義する、PushTopic レコードのクエリ項目。
• Apex の通常の動的な SOQL ステートメントのクエリ文字列。
SOQL は、SQL (Structured Query Language) の SELECT ステートメントに似た構文を使用して、
オブジェクトおよび項目を指定するために使用されます。たとえば、次のSOQLステー
トメントは、すべての Merchandise カスタムオブジェクトレコードのうち、Name の値
が「My Merchandise」であるレコードの ID 項目を返します。
SELECT Id FROM Merchandise__c WHERE Name = 'My Merchandise'
SOSL を使用するケース
データ検索文字列を作成する必要がある場合は常に SOSL を使用します。SOSL は、直
接は使用されず、他の Salesforce API 環境を介して使用されます。SOSL の使用例として
次のようなものがあります。
• search() SOAP API コール内の searchString パラメータ。
• REST API の search リソースで使用される検索要求パラメータ。
171
第 12 章 SOQL と SOSL
• Apex の通常の動的 SOSL ステートメントの検索文字列。
• Visualforce コントローラと getter メソッド。
SOSLは、特殊な検索構文を使用して、組織内のすべてのレコードを対象に検索するた
めのテキストを指定するために使用されます。たとえば、次の SOSL ステートメント
は、組織内のすべてのレコードのうち、いずれかのオブジェクトの Name 項目にテキ
スト「Joe Smith」または「Dan Fielding」が含まれるレコードの ID を返します。
FIND {"Joe Smith" OR "Dan Fielding"}
IN NAME FIELDS
サポート対象のエディションとプラットフォーム
SOQL と SOSL は、直接アクセスされる API ではないため、SOQL または SOSL を使用する
API のサポート対象エディションおよびプラットフォーム情報を参照してください。
すべての API が SOQL や SOSL をサポートしているわけではありません。また、これらを
使用する API の中には、使用可能な SOQL 句の一部しかサポートしていないものもあり
ます。たとえば、Bulk API の一括クエリは、ネストされたクエリと COUNT、ROLLUP、
SUM、GROUP BY CUBE、および OFFSET 句をサポートしていません。API での SOQL および
SOSL のサポート状況を判定するには、使用する各 API の開発者ガイドを参照してくだ
さい。
リソース
SOQL および SOSL に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• SOQL および SOSL リファレンスガイド
• API とインテグレーションに関するフォーラム
172
第 13 章
Apex
Apex は、Salesforce の組織のデータについてビジネスロジックとトリガを追加できるよ
うにする、オブジェクト指向のオンデマンドプログラミング言語です。
Apex を使用するケース
Apexは、開発者がForce.comプラットフォームサーバでフローとトランザクションの制
御ステートメントを Force.com API へのコールと組み合わせて実行できるようにした、
強く型付けされたオブジェクト指向のプログラミング言語です。Java に似た、データ
ベースのストアドプロシージャのように動作する構文を使用するApexにより、開発者
は、ボタンクリック、関連レコードの更新、および Visualforce ページなどのほとんど
のシステムイベントにビジネスロジックを追加できます。Apex コードは、Web サービ
ス要求、およびオブジェクトのトリガから開始できます。
次のような場合に Apex を使用します。
• Web サービスを作成する
• メールサービスを作成する
• 複数のオブジェクトに複雑な検証を実行する
• ワークフローでサポートされていない複雑なビジネスプロセスを作成する
• カスタムトランザクションロジック (1 つのレコードやオブジェクトだけでなく、
トランザクション全体で発生するロジック) を作成する
• レコードの保存などの別の操作にカスタムロジックを追加し、ユーザインター
フェース、Visualforce ページ、SOAP API のいずれから操作が実行されても、ロジック
が実行されるようにする
サポート対象のエディションとプラットフォーム
Apex は、Enterprise Edition、Performance Edition、Unlimited Edition、Developer Edition、および
Database.com に含まれています。既存の Salesforce のお客様が Enterprise Edition、Unlimited
173
第 13 章 Apex
Edition、または Performance Edition にアップグレードする場合は、担当者にご連絡くだ
さい。
Apex クイックスタート
Developer Edition または Sandbox 組織を入手したら、Apex の基本概念について学習する
必要があります。Apex は Java によく似ているため、多くの機能がなじみ深いもので
す。
基本を確認したら、最初のApexプログラムとして非常に単純なクラス、トリガおよび
単体テストを作成することができます。
さらに、もう少し複雑な納入先請求書の例を確認することもできます。この例では、
多数の言語機能を示します。
メモ: Hello World と納入先請求書のサンプルでは、カスタム項目およびオブジェ
クトが必要です。項目やオブジェクトを自分で作成したり、オブジェクト、項目
および Apex コードを管理パッケージとして Force.com AppExchange からダウンロー
ドできます。詳細は、https://developer.salesforce.com/docsを参照して
ください。
最初の Apex コードおよびトリガの作成
このステップごとのチュートリアルでは、簡単な Apex クラスおよびトリガを作成する
方法を説明します。また、これらのコンポーネントを本番組織にリリースする方法を
示します。
このチュートリアルは、最初のステップで作成される Book というカスタムオブジェク
トに基づいています。このカスタムオブジェクトはトリガを使用して更新されます。
カスタムオブジェクトの作成
前提条件:
Sandbox の Performance Edition、Unlimited Edition、または Enterprise Edition 組織の Salesforce
アカウント、または Developer Edition 組織のアカウント。
174
第 13 章 Apex
Sandbox組織の作成についての詳細は、Salesforceオンラインヘルプの「Sandboxの概要」
を参照してください。無償の Developer Edition 組織にサインアップするには、Developer
Edition 環境のサインアップページを参照してください。
このステップでは、Price というカスタム項目を持つ Book というカスタムオブジェクト
を作成します。
1. Sandbox または Developer Edition 組織にログインします。
2. [設定] から [作成] > [オブジェクト] をクリックし、[新規カスタムオブジェクト]
をクリックします。
3. 表示ラベルに「Book」と入力します。
4. 複数形の表示ラベルには「Books」と入力します。
5. [保存] をクリックします。
ご覧ください! 最初のカスタムオブジェクトを作成できました。次に、カスタム
項目を作成します。
6. Book の詳細ページの [カスタム項目 & リレーション] セクションで、[新規] をク
リックします。
7. データ型に [Number] を選択し、[次へ] をクリックします。
8. 項目の表示ラベルに「Price」と入力します。
9. 長さのテキストボックスに「16」と入力します。
10. 小数点の位置を指定するテキストボックスに「2」を入力し、[次へ]をクリック
します。
11. 項目レベルのセキュリティのデフォルト値を受け入れるには、[次へ] をクリッ
クします。
12. [保存] をクリックします。
Book というカスタムオブジェクトを作成し、それにカスタム項目を追加しました。カ
スタムオブジェクトには、Name や CreatedBy などの一部の標準の項目が含まれており、
より実装に固有の項目をさらに追加することができます。このチュートリアルでは、
Price 項目は Book オブジェクトの一部であり、アクセスするには次のステップで記述す
る Apex クラスを使用します。
Apex クラスの追加
前提条件:
175
第 13 章 Apex
• sandbox の Performance Edition、Unlimited Edition、または Enterprise Edition 組織の
Salesforce アカウント、または Developer Edition 組織のアカウント。
• Book カスタムオブジェクト。
このステップでは、本の価格を更新するメソッドを含むApexクラスを追加します。こ
のメソッドは、次のステップで追加するトリガでコールされます。
1. [設定] から [開発] > [Apex クラス] をクリックし、[新規] をクリックします。
2. クラスエディタで、次のクラス定義を入力します。
public class MyHelloWorld {
}
前述のコードは、次のステップで 1 つのメソッドを追加するクラス定義です。
Apex コードは、通常、クラスに含まれています。このクラスは public と定義
されているため、他のApexクラスおよびトリガで使用できます。詳細は、「ク
ラス、オブジェクトおよびインターフェース」を参照してください。
3. クラスの開き括弧および閉じ括弧の間にこのメソッド定義を追加します。
public static void applyDiscount(Book__c[] books) {
for (Book__c b :books){
b.Price__c *= 0.9;
}
}
このメソッドは applyDiscount と呼ばれ、公開かつ静的メソッドです。これ
は静的メソッドであるため、メソッドにアクセスするためにクラスのインスタ
ンスを作成する必要はありません。このメソッドにアクセスするには、クラス
名の後にカンマ (.)、メソッド名を指定します。詳細は、「静的およびインスタ
ンスメソッド」を参照してください。
このメソッドでは 1 つのパラメータ、Book レコードのリストを使用します。こ
れは変数 books に割り当てられます。オブジェクト名の後に __c を記述し、
176
第 13 章 Apex
Book__c とします。これは、この項目がカスタムオブジェクト、つまり自分で
作成した項目であることを示します。Account など Salesforce アプリケーションで
提供される標準オブジェクトの末尾はこのポストフィックスではありません。
コードの次のセクションでは、メソッド定義の残りを記述します。
for (Book__c b :books){
b.Price__c *= 0.9;
}
項目名の後に __c を記述し、Price__c とします。これは、この項目がカスタ
ム項目、つまり自分で作成した項目であることを示します。Salesforce のデフォ
ルトで提供されている標準項目へのアクセスには同じ種類のドット表記が使用
されますが、__c は使用されません。たとえば、Book__c.Name の Name 項目
の末尾に __c は付きません。ステートメント b.Price__c *= 0.9; では
b.Price__c の古い値を取り、この値を 0.9 で乗算します。つまり、10% 割り引
きされた値にします。次に、新しい値を b.Price__c 項目に保存します。*=
演算子はショートカットです。このステートメントを作成する他の方法は、
b.Price__c = b.Price__c * 0.9; です。「式の演算子について」を参照
してください。
4. [保存] をクリックすると、新しいクラスが保存されます。これで、次の完全な
クラス定義が設定されます。
public class MyHelloWorld {
public static void applyDiscount(Book__c[] books) {
for (Book__c b :books){
b.Price__c *= 0.9;
}
}
}
177
第 13 章 Apex
これで、Book (本) リストを反復処理し、各本の価格項目を更新するコードを含むクラ
スを作成できました。このコードは、次のステップで作成するトリガによってコール
される applyDiscount 静的メソッドの一部です。
Apex トリガの追加
前提条件:
• Sandbox の Performance Edition、Unlimited Edition、または Enterprise Edition 組織の
Salesforce アカウント、または Developer Edition 組織のアカウント。
• MyHelloWorld Apex クラス
このステップでは、前のステップで作成した MyHelloWorld クラスの applyDiscount
メソッドをコールする Book__c カスタムオブジェクトのトリガを作成します。
トリガは、Force.com プラットフォームデータベースで特定のタイプのレコードが挿
入、更新、または削除される前または後に実行するコードの一部です。各トリガは、
トリガが実行されるレコードへのアクセス権限を提供する一連のコンテキスト変数で
実行します。すべてのトリガは一括で実行します。つまり、複数のレコードを一度に
処理します。
1. [設定] から、[作成] > [オブジェクト] をクリックし、作成したオブジェクトの名
前 (Book) をクリックします。
2. [トリガ] セクションで、[新規] をクリックします。
3. トリガエディタで、デフォルトのテンプレートコードを削除し、このトリガの
定義を入力します。
trigger HelloWorldTrigger on Book__c (before insert) {
Book__c[] books = Trigger.new;
MyHelloWorld.applyDiscount(books);
}
178
第 13 章 Apex
コードの最初の行はトリガを定義します。
trigger HelloWorldTrigger on Book__c (before insert) {
このコードはトリガに名前を付け、トリガを実行するオブジェクトを指定し、
トリガを実行するイベントを定義します。たとえば、このトリガを
HelloWorldTrigger とし、Book__c オブジェクトで動作し、新しいブックがデータ
ベースに挿入される前に実行するようにします。
トリガの次の行は、books という名前のブックレコードのリストを作成し、
Trigger.new というトリガコンテキスト変数の内容を割り当てます。
Trigger.new などのトリガコンテキスト変数は、すべてのトリガで暗黙的に
定義され、トリガを実行するレコードにアクセスできるようにします。この場
合、Trigger.new には、挿入される新しいブックがすべて含まれます。
Book__c[] books = Trigger.new;
コードの次の行は、MyHelloWorld クラスのメソッド applyDiscount をコー
ルします。新しいブックの配列に渡します。
MyHelloWorld.applyDiscount(books);
挿入されるすべてのブックの価格を更新するために必要なすべてのコードが揃いまし
た。ただし、このパズルのピースが 1 つ不足しています。単体テストは、コードを記
述する上で重要な部分であり、必須です。次のステップでは、これが重要である理由
を確認し、テストクラスを追加できます。
テストクラスの追加
前提条件:
• Sandbox の Performance Edition、Unlimited Edition、または Enterprise Edition 組織の
Salesforce アカウント、または Developer Edition 組織のアカウント。
• HelloWorldTrigger Apex トリガ
このステップでは、1 つのテストメソッドを持つテストクラスを追加します。また、
テストを実行して、コードカバー率を検証します。テストメソッドはトリガとクラス
のコードを実行して検証します。また、トリガとクラスのコードカバー率が 100% に
達するようにします。
179
第 13 章 Apex
メモ: テストは開発プロセスの重要な部分です。Apex をリリースまたは Force.com
AppExchange 用にパッケージ化する前に、次の条件を満たす必要があります。
• Apex コードの少なくとも 75% が単体テストでカバーされており、かつすべて
のテストが成功している。
次の点に注意してください。
– 本番組織にリリースするときに、組織の名前空間内のすべての単体テスト
が実行されます。
– System.debug へのコールは、Apexコードカバー率の対象とはみなされま
せん。
– テストメソッドとテストクラスは、Apexコードカバー率の対象とはみなさ
れません。
– Apexコードの 75% が単体テストでカバーされている必要がありますが、カ
バー率を上げることだけに集中すべきではありません。アプリケーション
のすべての使用事例 (正・誤両方の場合や単一データだけでなく複数デー
タの場合) の単体テストを作成するようにしてください。このような多様
な使用事例のテストコードを実装することが 75% 以上のカバー率につなが
ります。
• すべてのトリガについて何らかのテストを行う。
• すべてのクラスとトリガが正常にコンパイルされる。
1. [設定] から [開発] > [Apex クラス] をクリックし、[新規] をクリックします。
2. クラスエディタで、このテストクラスの定義を追加し、[保存] をクリックしま
す。
@isTest
private class HelloWorldTestClass {
static testMethod void validateHelloWorld() {
Book__c b = new Book__c(Name='Behind the Cloud',
Price__c=100);
System.debug('Price before inserting new book: ' +
b.Price__c);
180
第 13 章 Apex
// Insert book
insert b;
// Retrieve the new book
b = [SELECT Price__c FROM Book__c WHERE Id =:b.Id];
System.debug('Price after trigger fired: ' + b.Price__c);
// Test that the trigger correctly updated the price
System.assertEquals(90, b.Price__c);
}
}
このクラスは、@isTest アノテーションを使用して定義されています。こうし
て定義されたクラスには、テストメソッドのみが含まれます。テスト用に個別
のクラスを作成することの利点の 1 つは、isTest で定義されたクラスは、す
べての Apex コードに対して組織で設定された 3 MB の制限の対象としてカウン
トされないことです。@isTest アノテーションを個別のメソッドに追加するこ
ともできます。詳細は、「IsTest アノテーション」および「実行ガバナと制
限について」を参照してください。
メソッド validateHelloWorld は testMethod として定義されます。つま
り、データベースに変更が行われると、実行の完了時に自動的にロールバック
され、テストメソッドで作成されたテストデータを削除する必要はありませ
ん。
181
第 13 章 Apex
まず、テストメソッドは新しいブックを作成し、データベースに一時的に挿入
します。System.debug ステートメントによって、デバッグログに価格の値が
書き込まれます。
Book__c b = new Book__c(Name='Behind the Cloud', Price__c=100);
System.debug('Price before inserting new book: ' + b.Price__c);
// Insert book
insert b;
ブックが挿入されると、コードは、挿入時にブックに割り当てられた ID を使用
して新たに挿入されたブックを取得し、トリガによって変更された新しい価格
を記録します。
// Retrieve the new book
b = [SELECT Price__c FROM Book__c WHERE Id =:b.Id];
System.debug('Price after trigger fired: ' + b.Price__c);
MyHelloWorld クラスが実行されると、Price__c 項目が更新され、値が 10%
減少します。次の行は実際のテストで、メソッド applyDiscount が実際に実
行され、予想どおりの結果が得られたことを検証します。
// Test that the trigger correctly updated the price
System.assertEquals(90, b.Price__c);
3. 次に、開発者コンソールに切り替えてこのテストを実行し、コードカバー率情
報を確認します。あなたの名前 > [開発者コンソール] をクリックします。
開発者コンソールウィンドウが開きます。
4. 開発者コンソールで、[Test (テスト)] > [New Run (新規実行)] をクリックします。
5. テストクラスを追加するには、[HelloWorldTestClass] をクリックし、[>] をクリッ
クします。
182
第 13 章 Apex
6. [実行] をクリックしてテストを実行します。
[Tests (テスト)] タブにテスト結果が表示されます。必要に応じて、[Tests (テスト)]
タブのテストクラスを展開して、実行されたメソッドを確認できます。この場
合、クラスには 1 つのテストメソッドのみが含まれます。
7. [Overall Code Coverage (全体のコードカバー率)] ペインに、このテストクラスのコー
ドカバー率が表示されます。このテストでカバーされたトリガ内のコードの行
(100%) を表示するには、[HelloWorldTrigger] のコードカバー率行をダブルクリッ
クします。また、トリガは MyHelloWorld クラスからメソッドをコールする
ため、このクラスにもカバー率 (100%) があります。クラスのカバー率を表示す
るには、[MyHelloWorld] をダブルクリックします。
8. [Logs (ログ)] タブのログリストで最新のログ行をダブルクリックして、ログファ
イルを開きます。実行ログが表示されます。このログには、トリガイベント、
applyDiscount クラスメソッドへのコール、およびトリガ前後の価格のデバッ
グ出力に関するログ情報が含まれます。
ここまでで、Apexコードを記述して開発環境でテストを実行するために必要なすべて
のステップを完了しました。実際に、コードを十分にテストして満足できる結果が得
られたら、他の要件のコンポーネントと共にコードを本番組織にリリースできます。
次のステップでは、コードと作成したカスタムオブジェクトを本番組織にリリースす
る方法を説明します。
本番組織へのコンポーネントのリリース
前提条件:
• Sandbox の Performance Edition、Unlimited Edition、または Enterprise Edition 組織の
Salesforce アカウント。
• HelloWorldTestClass Apex テストクラス
• 受信変更セットを本番組織で受信できるようにする、Sandbox と本番組織間のリ
リース接続。Salesforceオンラインヘルプの「変更セットの概要」を参照してくださ
い。
• 送信変更セットを作成、編集、またはアップロードするための「変更セットの作
成とアップロード」ユーザ権限
このステップでは、変更セットを使用して、以前に作成したApexコードとカスタムオ
ブジェクトを本番組織にリリースできます。
183
第 13 章 Apex
変更セットは Performance Edition、Unlimited Edition、Enterprise Edition、または Database.com
Edition 組織でのみ使用できるものであるため、この手順は、Developer Edition 組織には
適用されません。Developer Edition アカウントを使用している場合は、その他のリリー
スメソッドを使用できます。詳細は、「Apex のリリース」を参照してください。
1. [設定] で、[リリース] > [送信変更セット] をクリックします。
2. スプラッシュページが表示される場合は、[次へ] をクリックします。
3. [変更セット] リストで、[新規] をクリックします。
4. HelloWorldChangeSet など、変更セットの名前を入力し、必要に応じて説明
を入力します。[保存] をクリックします。
5. [変更セットコンポーネント] セクションで、[追加] をクリックします。
6. コンポーネントの種類のドロップダウンリストで [Apex] を選択してから、リス
トから MyHelloWorld クラスと HelloWorldTestClass クラスを選択し、[変更セットに
追加] をクリックします。
7. [連動関係を参照/追加] をクリックし、連動コンポーネントを追加します。
8. すべてのコンポーネントを選択するには、上部のチェックボックスをオンにし
ます。[変更セットに追加] をクリックします。
9. 変更セットページの [変更セットの詳細] セクションで、[アップロード]をクリッ
クします。
10. 対象組織 (この場合は本番組織) を選択し、[アップロード] をクリックします。
11. 変更セットのアップロードが完了したら、本番組織にリリースできます。
a. 本番組織にログインします。
b. [設定] で、[リリース] > [受信変更セット] をクリックします。
c. スプラッシュページが表示される場合は、[次へ] をクリックします。
d. リリース待ちの変更セットのリストで、変更セットの名前をクリックしま
す。
e. [リリース] をクリックします。
このチュートリアルでは、カスタムオブジェクトの作成方法、Apexトリガ、クラス、
およびテストクラスの追加方法を学習しました。最後に、コードのテスト方法や、変
更セットを使用したコードとカスタムオブジェクトのアップロード方法も学習しまし
た。
184
第 13 章 Apex
ベストプラクティス
このセクションのベストプラクティスを考慮してください。
クラウドでのコードの開発
Apex プログラミング言語は、クラウド (Force.com マルチテナントプラットフォーム) で
保存、実行されます。Apexはこのプラットフォームでのデータアクセスとデータ操作
用に設計されており、システムイベントにカスタムビジネスロジックを追加できま
す。プラットフォームでのビジネスプロセスを自動化する多数の利点がありますが、
一般的な用途のプログラミング言語ではありません。したがって、Apexは次の用途に
は使用できません。
• エラーメッセージ以外のユーザインターフェースの要素の表示
• 標準機能の変更。Apexでは、機能の実行または機能の追加の回避のみが可能です。
• 一時ファイルの作成
• スレッドの実行
ヒント: すべての Apex コードは、他のすべての組織で使用される共有リソースで
ある Force.com プラットフォーム上で実行されます。一貫したパフォーマンスと
拡張性を確保するため、Apex の実行は、Apex 実行が Salesforce のサービス全体に
一切影響を及ぼさないことを保証するガバナ制限によって制約されています。こ
れは、すべての Apex コードは、1 回のプロセスで実行できる操作数 (DML、SOQL
など) に限定されることを意味します。
すべての Apex 要求は、1 件から 50,000 件のレコードを含むコレクションを返しま
す。コードが一度に 1 つのレコードでしか機能しないことは考えられません。そ
のため、一括処理を考慮するプログラミングパターンを実装する必要がありま
す。そうでない場合、ガバナ制限による制約を受ける可能性があります。
テストの記述
テストは、長期間の開発を正常に行うための主要部分であり、開発プロセスの重要な
部分を占めます。テストコードを開発時に同時に作成する、テスト駆動型の開発プロ
セスで開発することを強くお勧めします。
185
第 13 章 Apex
堅牢で、エラーのないコードの開発を促進するため、Apexは単体テストの作成と実行
をサポートします。単体テストは、コード内の特定の部分が正しく機能していること
を確認するクラスメソッドです。単体テストのメソッドは引数を取らず、データベー
スへのデータの確定やメールの送信を行うこともなく、メソッド定義に testMethod
キーワードまたは isTest アノテーションでフラグが付けられています。また、テス
トメソッドは、テストクラス (isTest アノテーションが付加されているクラス) で定
義されている必要があります。
さらに、Apex をリリースまたは Force.com AppExchange 用にパッケージ化する前に、次
の条件を満たす必要があります。
• Apex コードの少なくとも 75% が単体テストでカバーされており、かつすべてのテ
ストが成功している。
次の点に注意してください。
– 本番組織にリリースするときに、組織の名前空間内のすべての単体テストが実
行されます。
– System.debug へのコールは、Apex コードカバー率の対象とはみなされませ
ん。
– テストメソッドとテストクラスは、Apexコードカバー率の対象とはみなされま
せん。
– Apex コードの 75% が単体テストでカバーされている必要がありますが、カバー
率を上げることだけに集中すべきではありません。アプリケーションのすべて
の使用事例 (正・誤両方の場合や単一データだけでなく複数データの場合) の単
体テストを作成するようにしてください。このような多様な使用事例のテスト
コードを実装することが 75% 以上のカバー率につながります。
• すべてのトリガについて何らかのテストを行う。
• すべてのクラスとトリガが正常にコンパイルされる。
テスト記述について詳細は、「Apex のテスト」を参照してください。
実行ガバナと制限について
Apex はマルチテナント環境で実行するため、Apex ランタイムエンジンは、回避 Apex
が共有リソースを独占しないようさまざまな制限事項を強制します。一部のApexコー
ドが制限を超える場合、関連付けられたガバナは、処理できない実行時例外を発行し
ます。
186
第 13 章 Apex
Apex制限、つまりガバナでは、次の表とセクションで示される統計情報を追跡し、強
制的に適用します。
• トランザクション単位の Apex 制限
• トランザクション単位の認定管理パッケージの制限
• Force.com プラットフォームの Apex 制限
• 静的 Apex の制限
• サイズ固有の Apex 制限
• その他の Apex の制限
このトピックでは、コアApexガバナ制限に加え、メール制限や転送通知の制限も参照
しやすいように、この後に含まれています。
トランザクション単位の Apex 制限
これらの制限は、Apexトランザクション単位でカウントされます。Apexの一括処理の
場合、これらの制限は execute メソッドでレコードのバッチの実行ごとにリセット
されます。
次の表では、同期 Apex と非同期 Apex (Apex の一括処理と future メソッド) が異なる場
合、それぞれの制限を記載しています。制限が同じ場合、表には、同期および非同期
Apex の両方に適用される 1 つの制限のみが記載されます。
説明
発行される SOQL クエリの合計数1
同期 Apex
の制限
非同期 Apex
の制限
100
200
SOQL クエリによって取得されるレコードの合計数
50,000
Database.getQueryLocator によって取得されるレコー
10,000
ドの合計数
発行される SOSL クエリの合計数
20
1 つの SOSL クエリによって取得されるレコードの合計数
発行される DML ステートメントの合計数2
187
2,000
150
第 13 章 Apex
説明
同期 Apex
の制限
非同期 Apex
の制限
DML ステートメント、Approval.process、または
database.emptyRecycleBin の結果として処理される
レコードの合計数
10,000
insert、update、または delete ステートメントによっ
16
て繰り返しトリガするApex呼び出しのスタックの深さの
合計 3
トランザクション内のコールアウト (HTTP 要求または Web
サービスコール) の合計数
100
トランザクション内のすべてのコールアウト (HTTP 要求
または Web サービスコール) の最大タイムアウト値
120 秒
Apex呼び出し 1 回につき許可される future アノテーショ
ンを持つメソッドの最大数
50
System.enqueueJob によってキューに追加される Apex
50
ジョブの最大数
許可される sendEmail メソッドの合計数
ヒープの合計サイズ 5
Salesforce サーバの最大 CPU 時間6
Apex トランザクションごとの最大実行時間
10
6 MB
12 MB
10,000 ミリ
秒
60,000 ミリ
秒
10 分
参照される固有の名前空間の最大数7
10
Apex トランザクションごとに許容される転送通知メソッ
ドコールの最大数
10
各転送通知メソッドコールで送信できる転送通知の最大
数
2,000
188
第 13 章 Apex
1
親-子リレーションのサブクエリを使用する SOQL クエリでは、各親-子リレーション
は追加クエリとしてカウントされます。これらのクエリタイプには、最上位クエリ数
の 3 倍に制限されています。これらのリレーションクエリの行数は、全体のコード実
行の行数に加算されます。静的 SOQL ステートメントの他、次のメソッドへのコール
は、要求内で発行された SOQL ステートメント数としてカウントされます。
• Database.countQuery
• Database.getQueryLocator
• Database.query
2
次のメソッドへのコールは、要求内で発行された DML クエリ数としてカウントされ
ます。
• Approval.process
• Database.convertLead
• Database.emptyRecycleBin
• Database.rollback
• Database.setSavePoint
• delete と Database.delete
• insert と Database.insert
• merge および Database.merge
• undelete と Database.undelete
• update と Database.update
• upsert と Database.upsert
• System.runAs
3
insert、update、または delete ステートメントによってトリガを実行しない繰
り返し Apex 処理は、1 つのスタックを使用する 1 つの呼び出し内に存在します。それ
に対し、トリガを実行した繰り返しApexでは、コードを実行した呼び出しとは別の新
しい Apex 呼び出しでトリガが発生します。Apex の新しい呼び出しの実行は、1 つの呼
び出しでの繰り返しコールよりも手間のかかる操作であるため、これらの種類の繰り
返しコールのスタックの深さには、より厳しいトリガ制限があります。
4
メールサービスのヒープサイズは 36 MB です。
5
CPU 時間は、1 つの Apex トランザクションで発生する Salesforce アプリケーションサー
バ上でのすべての実行 (Apex コードや、このコードからコールされるすべてのプロセ
ス (パッケージコードやワークフローなど) の実行) に対して計算されます。CPU 時間
189
第 13 章 Apex
は、1 つのトランザクション専用であり、他のトランザクションからは独立していま
す。アプリケーションサーバの CPU 時間を消費しない操作は、CPU 時間には加算され
ません。 たとえば、実行時間のうち DML、SOQL、および SOSL 用のデータベースに費
やされた時間や、Apex コールアウトの待ち時間はカウントされません。
6
1 つのトランザクションでは、10 個の一意の名前空間のみを参照できます。たとえ
ば、オブジェクトを更新するときに、管理パッケージでクラスを実行するオブジェク
トがあるとします。その後、クラスは 2 番目のオブジェクトを更新します。つまり、
他のパッケージの他のクラスを実行します。最初に 2 番目のパッケージに直接アクセ
スしない場合でも、同じトランザクション内で発生するため、1 つのトランザクショ
ンでアクセスする名前空間の数に含まれます。
メモ:
• 制限は、各 testMethod に対して個別に適用されます。
• 実行中にコードのコード実行制限を決定するには、Limits メソッドを使用しま
す。たとえば、プログラムによってすでにコールされた DML ステートメント
数を決定するには、getDMLStatements メソッドを使用できます。または、
コードに使用できる DML ステートメントの合計数を決定するには、
getLimitDMLStatements メソッドを使用できます。
トランザクション単位の認定管理パッケージの制限
認定管理パッケージ (AppExchange のセキュリティレビューに合格した管理パッケージ)
には、一部の制限を除き、トランザクション単位の制限に対して独自の制限セットが
設けられます。認定管理パッケージは Salesforce ISV パートナーによって開発され、
Force.com AppExchange から組織にインストールされ、固有の名前空間を持ちます。
ここでは、DML ステートメントについて、認定管理パッケージに別個に設定される制
限の例を説明します。認定管理パッケージをインストールすると、そのパッケージ内
のすべての Apex コードには、組織のネイティブコードが実行できる 150 個の DML ス
テートメントに加え、独自に 150 個の DML ステートメントの制限が設定されます。つ
まり、管理パッケージのコードとネイティブの組織のコードの両方が実行されると、
1 つのトランザクションで 150 個を超える DML ステートメントが実行される可能性が
あります。同様に、同期Apexについては、認定管理パッケージには組織のネイティブ
コードの 100 個の SOQL クエリ制限に加え、独自に 100 個の SOQL クエリ制限が設定さ
れます。他の制限についても同様です。
190
第 13 章 Apex
認定管理パッケージでは、次を除くすべてのトランザクション単位の制限は個別にカ
ウントされます。
• ヒープの合計サイズ
• 最大 CPU 時間
• 最大トランザクション実行時間
• 一意の名前空間の最大数
これらの制限は、同じトランザクションで実行されている認定管理パッケージの数に
関係なく、トランザクション全体に対してカウントされます。
また、Salesforce ISV パートナー以外が作成した未認定の AppExchange からパッケージを
インストールする場合、そのパッケージのコードには、別個に独自のガバナ制限数は
ありません。使用するリソースは、組織の合計数に含まれます。累積リソースメッ
セージと警告メールも、管理パッケージの名前空間に基づいて生成されます。
Salesforce ISV パートナーパッケージの詳細は、「Salesforce Partner Programs」を参照して
ください。
Force.com プラットフォームの Apex 制限
次の表の制限は、Apexトランザクションに固有ではなく、Force.com プラットフォーム
によって適用されます。
説明
制限
24 時間あたりの非同期 Apex メソッド実行 (Apex 一括処理、future 250,000か、組織内の
メソッド、キュー可能 Apex、およびスケジュール済み Apex) の ユーザライセンス数
最大数1
ﾗ 200 の大きい方の
値
組織ごとの、5 秒以上かかる長時間の要求に対する同期同時要 10
求数。2
同時にスケジュールされる Apex クラスの最大数
100
Apex Flex キューに入っている Holding 状況のApex一括処理ジョ 100
ブの最大数
191
第 13 章 Apex
説明
制限
同時にキューに入っているか有効な Apex 一括処理ジョブの最
大数3
5
Apex 一括処理ジョブの start メソッドの最大同時実行数4
1
1 つのテストの実行で送信可能な一括処理ジョブの最大数
5
24 時間あたりのキュー可能なテストクラスの最大数 (Developer
Edition 以外の本番組織)5
500 または組織のテ
ストクラス数の 10
倍の大きいほう
24 時間あたりのキュー可能なテストクラスの最大数 (Sandbox お 500 または組織のテ
よび Developer Edition 組織)5
ストクラス数の 20
倍の大きいほう
ユーザごとに同時に開くクエリカーソルの最大数6
50
Apex 一括処理の start メソッドでユーザごとに同時に開くク 15
エリカーソルの最大数
Apex 一括処理の execute および finish メソッドでユーザご 5
とに同時に開くクエリカーソルの最大数
1
Apex一括処理の場合、メソッド実行には、start、execute、および finish メソッ
ドの実行が含まれます。これは組織全体の制限で、他のすべての非同期 Apex (Apex 一
括処理、キュー可能 Apex、スケジュール済み Apex、および future メソッド) と共有され
ます。この制限のカウント対象となるライセンスは、Salesforce フルユーザライセンス
またはForce.comアプリケーションサブスクリプションのユーザライセンスです。Chatter
Free、Chatter カスタマーユーザ、カスタマーポータルユーザ、およびパートナーポー
タルユーザライセンスは含まれません。
2
10 個の長時間の要求が実行されている間に追加の要求を行うと、要求は拒否されま
す。
3
一括処理ジョブが送信されると、処理用にシステムキューに移動されるまで、Flex
キューに保持されます。
4
キュー内のまだ開始されていない一括処理ジョブは、開始されるまで保持されます。
なお、この制限により一括処理ジョブが失敗することはありません。また、複数の
192
第 13 章 Apex
ジョブが実行されている場合は、Apex の一括処理ジョブの execute メソッドが並行
して実行されます。
5
この制限は、テストの非同期実行に適用されます。これには、開発者コンソールを
含め、Salesforce ユーザインターフェースから開始するテストが含まれます。
6
たとえば、50 個のカーソルが開いていて、同じユーザとしてログインしたままのク
ライアントアプリケーションが新しいカーソルを開こうとすると、50 個のカーソルの
うち最も古いカーソルが解放されます。異なるForce.com機能のカーソル制限は個別に
追跡されます。たとえば、50 個の Apex クエリカーソル、Apex 一括処理の start メ
ソッドに 15 個のカーソル、 Apex一括処理の execute および finish メソッドにそれ
ぞれ 5 個のカーソル、および 5 個の Visualforce カーソルを同時に開くことができます。
静的 Apex の制限
説明
制限
トランザクション内のコールアウト (HTTP 要求または Web サー 10 秒
ビスコール) のデフォルトのタイムアウト値
コールアウト要求または応答 (HTTP 要求または Web サービス
コール) の最大サイズ 1
同期 Apex の場合は 6
MB、非同期 Apex の
場合は 12 MB
SOQL クエリの最大実行時間。この時間を超えると、Salesforceで 120 秒
トランザクションをキャンセルできます。
Apex リリース内のクラスとトリガの最大コードユニット数
5,000
ループリストのバッチサイズ用
200
Database.QueryLocator の 1 回の Apex 一括処理クエリで返 5000 万
される最大レコード数
1
HTTP 要求のサイズおよび応答のサイズは、ヒープサイズの合計にカウントされます。
193
第 13 章 Apex
サイズ固有の Apex 制限
説明
制限
クラスの最大文字数
100 万
トリガの最大文字数
100 万
組織内のすべての Apex コードで使用されるコードの最大量1
3 MB
メソッドのサイズ制限 2
コンパイル形式で
65,535 バイトコード
命令
1
この制限は、AppExchange からインストールされた認定管理パッケージ (AppExchange
Certified とマークされたアプリケーション) には適用されません。これらのパッケージ
タイプのコードは、組織のコードとは異なる独自の名前空間に属しています。
AppExchange Certified パッケージについての詳細は、Force.com AppExchange オンラインヘ
ルプを参照してください。この制限は、@isTest アノテーションで定義されたクラ
スに含まれるコードにも適用されません。
2
制限を超える大規模なメソッドはコードの実行中に例外が発生する場合があります。
その他の Apex の制限
SOQL クエリのパフォーマンス
最高のパフォーマンスを得るためには、特にトリガ内のクエリに対しては、セレ
クティブ SOQL クエリを使用する必要があります。実行時間が長時間に渡ることを
回避するために、セレクティブ以外の SOQL クエリはシステムより終了される場合
があります。100,000 件を超えるレコードを含むオブジェクトに対してトリガでセ
レクティブではないクエリを使用すると、エラーメッセージが表示されます。こ
のエラーを回避するには、必ずセレクティブクエリを使用します。「より効率的
な SOQL クエリ」を参照してください。
Chatter in Apex
ConnectApi 名前空間内のクラスの場合、各書き込み操作が Apex ガバナ制限で 1
回の DML 操作としてカウントされます。ConnectApi メソッドコールも、レート
制限の対象となります。ConnectApi レート制限は、Chatter REST API レート制限と
194
第 13 章 Apex
同じです。どちらにも、ユーザごと、名前空間ごと、時間ごとのレート制限があ
ります。レート制限を超えると、ConnectApi.RateLimitException が発生しま
す。Apex コードで、この例外をキャッチして処理する必要があります。
イベントレポート
システム管理者以外のユーザの場合、イベントレポートが返すレコードの最大数
は 20,000 件です。システム管理者の場合、100,000 件です。
Data.com クリーンアップ
Data.comクリーンアップ製品とその自動ジョブを使用していて、取引先、取引先責
任者、またはリードレコードで実行する SOQL クエリの Apex トリガを設定している
場合、それらのオブジェクトでクエリがクリーンアップジョブに干渉する可能性
があります。Apex トリガ (合計) は、バッチあたり 200 個以下の SOQL クエリにして
ください。この制限を超えると、そのオブジェクトに対するクリーンアップジョ
ブが失敗します。また、トリガが future メソッドをコールする場合は、バッチ
あたり 10 個の future コールに制限されます。
メール制限
受信メール制限
メールサービス: 処理メールメッセージの最大数
(オンデマンドメール-to-ケースの制限を含む)
ユーザライセンス数 x
1,000、1 日あたりの最大数
1,000,000
1
メールサービス: メールメッセージの最大サイズ (本文 10 MB
および添付ファイル)
オンデマンドメール-to-ケース: メールの添付ファイル 25 MB
の最大サイズ
オンデマンドメール-to-ケース: 処理するメールメッ
セージの最大数
(メールサービスの制限に対してカウントする)
1
ユーザライセンス数 x
1,000、1 日あたりの最大数
1,000,000
メールサービスのメールメッセージの最大数は、言語および文字セットによって
異なります。
195
第 13 章 Apex
メールサービスを定義するときには、次の点に注意してください。
• メールサービスは、そのアドレスの 1 つが受信したメッセージを処理するだけ
です。
• Salesforce は、[オンデマンドメール-to-ケース] など、すべてのメールサービスを
合計した 1 日に処理できるメッセージの総数を制限します。この制限を超えた
メッセージは、各メールサービスの失敗時のレスポンス設定に基づいて、戻さ
れる、破棄される、あるいは翌日処理するためのキューに入れられます。Salesforce
は、ユーザライセンス数 x 1,000 で制限値を算出します。1 日の最大は 1,000,000
件です。たとえば、ライセンス数が 10 の場合、1 日最大 10,000 件のメールメッ
セージを処理できます。
• sandbox 内に作成したメールサービスアドレスは、本番組織にコピーできませ
ん。
• メールサービスごとに Salesforce に通知して、送信者のメールアドレスではな
く、特定のアドレスにエラーメールメッセージを送信できます。
• メールが (本文テキスト、本文 HTML および添付ファイルを合わせて) 約 10 MB を
超える場合 (言語や文字セットに応じて異なる)、メールサービスはメールメッ
セージを拒否し、送信者に通知します。
送信メール: Apex を使用して送信する単一メールおよび一括メールの制限
APIまたはApexを使用して、グリニッジ標準時間 (GMT) に基づいて、1 日に最大1,000
個の外部メールアドレスに単一メールを送信できます。Salesforceアプリケーション
を使用して送信する単一メールはこの制限にカウントされません。取引先、取引
先責任者、リード、商談、ケース、キャンペーン、カスタムオブジェクトの各ペー
ジから、組織の取引先責任者、リード、個人取引先、ユーザに個別のメールを送
信する場合は、制限はありません。
単一メールを送信する場合は、次の点に注意してください。
• SingleEmailMessage ごとに 100 個までのメールを送信できます。
• SingleEmailMessage を使用して組織の内部ユーザにメールを送信するとき
に setTargetObjectId でユーザ ID を指定すると、メールが 1 日あたりの制限
値にカウントされません。ただし、setToAddresses で内部ユーザのメールア
ドレスを指定すると、制限値にカウントされます。
グリニッジ標準時間 (GMT) に基づいて、1 組織あたり 1 日に合計 1,000 個の外部メー
ルアドレスに一括メール送信できます。各一括メール送信に含むことのできる外
部メールアドレスの最大数は、次のようにエディションに応じて異なります。
196
第 13 章 Apex
エディション
一括メール送信あたりの外部アドレス
制限
Personal Edition、Contact Manager Edition、お 一括メール送信は使用できません
よび Group Edition
Professional Edition
100
Enterprise Edition
500
Unlimited Edition および Performance Edition
1,000
メモ: 次のメール制限に注意してください。
• 単一メールおよび一括メールの制限では、アドレスが一意であるかどうか
は考慮されません。たとえば、メールに [email protected] が 10 回
含まれている場合、制限に対して 10 とカウントされます。
• ポータルユーザを含め、組織の内部ユーザに送信できるメールには制限は
ありません。
• Developer Edition 組織とトライアルで Salesforce を評価中の組織では、1 日あ
たり 10 個を超える外部メールアドレスに一括メール送信できません。こ
の低い制限は、組織が Winter '12 リリースより前に作成されており、一括
メール送信がすでに高い制限で有効になっている場合は適用されません。
また、組織は 1 日あたり最大 15 個のメールアドレスに単一メールを送信で
きます。
転送通知の制限
Salesforce 組織に関連付けられた各モバイルアプリケーションで許容される転送通知の
最大数は、アプリケーションの種別によって異なります。
許容される転送通知の最大数
制限
Salesforce によって提供されるモバイルアプリケーション
(Salesforce1 など)
アプリケーションご
とに 50,000 件/日の通
知
197
第 13 章 Apex
許容される転送通知の最大数
制限
社内の従業員が使用するために組織で開発されたモバイルアプ アプリケーションご
リケーション
とに 35,000 件/日の通
知
AppExchange からインストールされたモバイルアプリケーショ
ン
アプリケーションご
とに 5,000 件/日の通
知
配信可能な通知のみがこの制限にカウントされます。たとえば、通知が会社の 1,000
名の従業員に送信されるが、100 名の従業員はまだモバイルアプリケーションをイン
ストールしていない場合を考えます。この制限にカウントされるのは、モバイルアプ
リケーションをインストールしている 900 名の従業員に送信された通知のみです。
[転送通知をテスト] ページで生成された各テスト転送通知の受信者は 1 名に制限され
ています。テスト転送通知は、アプリケーションの 1 日の転送通知制限にカウントさ
れます。
リソース
Apex に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• Apex コード開発者ガイド
• Apex 早見表
• Apex ワークブック
• Apex 開発フォーラム
198
第 14 章
Visualforce
Visualforce は、Salesforce でホストできる高度なカスタムユーザインターフェースを HTML
に似たタグベースのマークアップ言語を使用して開発者が作成できるようにするフ
レームワークです。
Visualforce を使用するケース
Visualforceでは、タグベースのマークアップ言語を使用して、開発者はより効果的にア
プリケーションを開発したり、Salesforce のユーザインターフェースをカスタマイズし
たりできます。Visualforce を使用して、次のことができます。
• ウィザードやその他のマルチステッププロセスの構築
• アプリケーションを介した独自のカスタムフローコントロールの作成
• 最適かつ効果的なアプリケーションの相互作用を目的とした、ナビゲーションパ
ターンやデータ固有ルールの定義
Visualforce マークアップ言語では、各 Visualforce タグが、ページのセクション、関連リ
スト、または項目など、大まかなユーザインターフェースコンポーネントまたはきめ
の細かいユーザインターフェースコンポーネントに対応しています。Visualforce コン
ポーネントの動作は、標準のSalesforceページと同じロジックを使用して制御すること
も、開発者が独自のロジックをApexで記述されたコントローラクラスと関連付けるこ
ともできます。
サポート対象のエディションとプラットフォーム
Visualforce は、Contact Manager Edition、Group Edition、Professional Edition、Enterprise Edition、
Unlimited Edition、Performance Edition、および Developer Edition で使用できます。
Visualforce の開発には、特定の活動に応じてさまざまな権限が必要です。
199
第 14 章 Visualforce
必要なユーザ権限
Visualforce 開発モードを有効化する
「アプリケーションのカスタマイズ」
Visualforce ページを作成、編集、削除する 「アプリケーションのカスタマイズ」
カスタム Visualforce コンポーネントを作
成、編集する
「アプリケーションのカスタマイズ」
カスタム Visualforce コントローラまたは
Apex を編集する
「Apex 開発」
Visualforce ページセキュリティを設定する 「プロファイルと権限セットの管理」
Visualforce ページのバージョン設定を行う 「アプリケーションのカスタマイズ」
静的リソースを作成、編集、削除する
「アプリケーションのカスタマイズ」
Visualforce タブを作成する
「アプリケーションのカスタマイズ」
クイックスタート
Visualforceの重要な要素を紹介するために、この章には言語の機能を説明する例のセッ
トが含まれています。これらの例は、すべてのタグやコントローラのあらゆる詳細、
ルール、または例外を網羅するものではありませんが、Visualforceを初めて使用する開
発者は、このチュートリアルで、Visualforceがどのように機能するかを理解することが
できます。
最初のページの作成
開発モードが有効な場合、ブラウザのアドレスバーに次のようなページの URL を入力
することによって、最初の Visualforce ページを作成できます。
https://Salesforce_instance/apex/myNewPageName
たとえば、「HelloWorld」というページを作成するときに、Salesforce 組織が
na3.salesforce.com を使用している場合、
「http://na3.salesforce.com/apex/HelloWorld」と入力します。
200
第 14 章 Visualforce
ページはまだ存在しないため、中間ページが表示され、そこから新規ページを作成で
きるようになっています。[[Create Page <myNewPageName> (ページ nameOfNewPage
を作成)]] をクリックして、自動的に作成します。
メモ: Visualforce 開発モードが有効でない場合は、[設定] で [開発] > [ページ] をク
リックしてから [新規] をクリックし、新しいページを作成できます。
Visualforceページは、セットアップのこの部分以降で常に編集できるようになりま
すが、編集の結果を確認するには、ページの URL に移動する必要があります。そ
のため、ほとんどの開発者は、開発モードを有効にして作業することによって単
一のウィンドウでページの参照と編集を行うことを好みます。
新しい Visualforce ページ
デフォルトのテキストを含む Visualforce ページが表示されました。新しいページを編
集するには、ブラウザの下に表示されている[ページエディタ]のバーをクリックしま
す。ページエディタが展開されて、次の Visualforce マークアップが表示されます。
<apex:page>
<!-- Begin Default Content REMOVE THIS -->
<h1>Congratulations</h1>
This is your new Apex Page: HelloWorld
<!-- End Default Content REMOVE THIS -->
201
第 14 章 Visualforce
</apex:page>
このデフォルトのマークアップには、すべてのページに必要な <apex:page> タグ
(ページのマークアップを開始/終了するタグ) のみが含まれます。<apex:page> の開
始タグと終了タグに組み込まれているのはプレーンテキストで、一部は <h1> 標準
HTML タグでフォーマットされています。
必須の <apex:page> タグを維持するかぎり、プレーンテキストや有効な HTML をこ
のページに必要なだけ追加できます。たとえば、ページエディタに次のコードを入力
して [Save (保存)] をクリックすると、ページに「Hello World!」という太字のテキストが
表示されます。
<apex:page>
<b>Hello World!</b>
</apex:page>
ヒント: 警告には注意してください。開始タグに一致する終了タグがない HTML
が含まれているページを保存すると、Visualforceエディタに警告が表示されます。
ページは保存されますが、不正な形式の HTML は、表示されるページに問題を引
き起こす原因となります。
Visualforce による項目値の表示
Visualforce ページでは、数式と同じ式の言語を使用します。つまり、{! } 内のすべて
が、現在コンテキストにあるレコードから得られる値にアクセスできる式として評価
されます。たとえば、{!$User.FirstName} 式をページに追加すると、現在のユー
ザの「名」を表示できます。
<apex:page>
Hello {!$User.FirstName}!
</apex:page>
$User は、現在のユーザレコードを常に表すグローバル変数です。すべてのグローバ
ル変数は、$ 記号で参照されます。Visualforce で使用できるグローバル変数のリストに
ついては、「グローバル変数」を参照してください。
202
第 14 章 Visualforce
特定の取引先、取引先責任者、またはカスタムオブジェクトレコードなど、グローバ
ルに使用できるようになっていないレコードの項目にアクセスするには、ページをコ
ントローラに関連付ける必要があります。コントローラを使用すると、特定のオブ
ジェクトのレコードにアクセスする方法を指定するロジックなど、アプリケーション
を実行するためのデータやビジネスロジックをページで使用できます。ページのカス
タムコントローラはApexを使用して定義できますが、Salesforceには、すべての標準お
よびカスタムオブジェクトに使用できる標準コントローラが含まれています。
たとえば、取引先に対して標準コントローラを使用するには、<apex:page> タグに
standardController 属性を追加し、取引先オブジェクトの名前を割り当てます。
<apex:page standardController="Account">
Hello {!$User.FirstName}!
</apex:page>
ページを保存したら、ページの [取引先] タブが強調表示され、ページのコンポーネン
トのデザインが [取引先] タブに適用されます。さらに、{!account.<fieldName>}
式の構文を使用して、現在コンテキストにある取引先レコードの項目にアクセスでき
るようになります。
たとえば、取引先の名前をページに表示するには、ページのマークアップで
{!account.name} を使用します。
<apex:page standardController="Account">
Hello {!$User.FirstName}!
<p>You are viewing the {!account.name} account.</p>
</apex:page>
{!account.name} 式は、標準取引先コントローラの getAccount() メソッドにコー
ルし、現在コンテキストにある取引先のレコード ID を返します。その後、ドット表記
を使用してそのレコードの name 項目にアクセスします。
メモ: この式の言語を使用して親オブジェクトにアクセスすることはできませ
ん。言い換えると、{!account.parent.name} はエラーを返します。
メモ: ページを保存すると、<apex:inputField>、<apex:inputText> など、
すべての入力コンポーネントの value 属性について、文字テキストや空白を含
203
第 14 章 Visualforce
まない単一式であり、単一のコントローラメソッドまたはオブジェクトプロパ
ティへの有効な参照であるかどうかが検証されます。エラーが発生するとページ
を保存できません。
取引先レコードを現在のコンテキストに取り込むには、レコードの ID を指定するペー
ジ URL にクエリパラメータを追加する必要があります。手順は、次のとおりです。
1. 任意の方法で、取引先の ID を検索します。そのための簡単な方法として、取引
先レコードの詳細ページを表示し、URL の最後にある文字コードをコピーする
やり方があります。たとえば、次の URL で取引先詳細ページに移動するとしま
す。
https://na3.salesforce.com/001D000000IRt53
この場合、001D000000IRt53 が取引先の ID になります。
2. ページに戻り、ブラウザのアドレスバーの URL にクエリ文字列パラメータとし
て取引先 ID を追加します。たとえば、ページが次の場所にあったとします。
https://na3.salesforce.com/apex/HelloWorld2
URL の最後に ?id=001D000000IRt53 を追加します。
https://Salesforce_instance/apex/HelloWorld2?id=001D000000IRt53
メモ: URL に id パラメータを使用する場合、そのパラメータは、標準コントロー
ラで参照されるエンティティと同じエンティティを参照する必要があります。
取引先 ID を URL に指定したら、次の図のようにページに適切な取引先名が表示されま
す。
204
第 14 章 Visualforce
Visualforce ページの取引先データの表示
Visualforce コンポーネントライブラリの使用
ここまでで、例に使用された唯一の Visualforce タグは、すべての Visualforce マークアッ
プの先頭と末尾に配置する必要がある必須の <apex:page> タグです。ただし、<img>
または <table> タグを使用して HTML ドキュメントに画像やテーブルを挿入できるの
と同様に、Visualforceコンポーネントライブラリに定義されたタグを使用して、Visualforce
ページにユーザインターフェースコンポーネントを追加できます。
たとえば、詳細ページでセクションのように見えるコンポーネントを追加するには、
<apex:pageBlock> コンポーネントタグを使用します。
<apex:page standardController="Account">
<apex:pageBlock title="Hello {!$User.FirstName}!">
You are viewing the {!account.name} account.
</apex:pageBlock>
</apex:page>
205
第 14 章 Visualforce
<apex:pageBlock> コンポーネント
タグは、関連リスト、詳細ページ、および入力項目などの、一般的な Salesforce イン
ターフェースコンポーネント用にも存在します。たとえば、詳細ページのコンテンツ
を追加するには、<apex:detail> コンポーネントタグを使用します。
<apex:page standardController="Account">
<apex:pageBlock title="Hello {!$User.FirstName}!">
You are viewing the {!account.name} account.
</apex:pageBlock>
<apex:detail/>
</apex:page>
206
第 14 章 Visualforce
属性がない <apex:detail> コンポーネント
タグに特定の属性が何も指定されていなくても、<apex:detail> は、コンテキスト
レコードの完全な詳細ビューを表示します。どのレコードの詳細を表示するか、関連
リストやタイトルを表示するかなど、プロパティを変更するにはタグで属性を使用で
きます。たとえば、次のマークアップは、コンテキストの取引先所有者の詳細を表示
しますが、関連リストや色付きのタイトルバーは表示しません。
<apex:page standardController="Account">
<apex:pageBlock title="Hello {!$User.FirstName}!">
You are viewing the {!account.name} account.
</apex:pageBlock>
<apex:detail subject="{!account.ownerId}" relatedList="false"
title="false"/>
</apex:page>
207
第 14 章 Visualforce
関連リストまたはタイトル要素のない <apex:detail> コンポーネント
コンポーネントライブラリを参照するには、ページエディタで [Component Reference
(コンポーネントの参照)]をクリックします。このページから、任意のコンポーネント
にドリルダウンして、定義した任意のカスタムコンポーネントを含め、各コンポーネ
ントで使用可能な属性を参照できます。
ページでの入力コンポーネントの使用
ここまでは、このクイックスタートチュートリアルの例で、Visualforceページにデータ
を表示できる方法を説明しました。ユーザの入力を取得するには、1 つ以上の入力コ
ンポーネントを含む <apex:form> タグと、フォームを送信するための
<apex:commandLink> タグまたは <apex:commandButton> タグを使用します。
フォームでもっとも使用される入力コンポーネントタグは <apex:inputField> で
す。このタグは、標準またはカスタムオブジェクト項目の種別に基づいて適切な入力
ウィジェットを表示します。たとえば、データ項目を表示するために
<apex:inputField> タグを使用すると、カレンダーウィジェットがフォーム上に表
示されます。選択リスト項目を表示するために <apex:inputField> タグを使用す
ると、代わりにドロップダウンリストが表示されます。<apex:inputField> タグ
は、任意の標準またはカスタムオブジェクト項目のユーザ入力を取得するために使用
208
第 14 章 Visualforce
できます。このタグは、項目が必須または一意であるか、あるいは現在のユーザに表
示または編集の権限があるかなど、項目の定義に設定されているすべてのメタデータ
を順守します。
たとえば、次のページでは、ユーザは取引先の名前の編集と保存を行えます。
メモ: このページに取引先データを表示するには、有効な取引先レコードの ID を
ページの URL のクエリパラメータとして指定する必要があります。次に例を示し
ます。
https://Salesforce_instance/apex/myPage?id=001x000xxx3Jsxb
レコードの ID の取得についての詳細は、「Visualforce による項目値の表示」 (ペー
ジ 202)を参照してください。
<apex:page standardController="Account">
<apex:form>
<apex:pageBlock title="Hello {!$User.FirstName}!">
You are viewing the {!account.name} account. <p/>
Change Account Name: <p/>
<apex:inputField value="{!account.name}"/> <p/>
<apex:commandButton action="{!save}" value="Save New Account
Name"/>
</apex:pageBlock>
</apex:form>
</apex:page>
この例では、次の点に留意してください。
• <apex:inputField> タグは、タグの value 属性を設定することによって、取引
先の name 項目にバインドされます。式には、ページのほかの場所に項目の値を
表示するためによく使用される {!account.name} ドット表記が含まれます。
209
第 14 章 Visualforce
• <apex:commandButton> タグには、action 属性があります。この属性の値は、
標準取引先コントローラの save アクションを呼び出します。このアクションは、
標準の取引先編集ページの [保存] ボタンと同じ動作を実行します。
メモ: ページを保存すると、<apex:inputField>、<apex:inputText> など、
すべての入力コンポーネントの value 属性について、文字テキストや空白を含
まない単一式であり、単一のコントローラメソッドまたはオブジェクトプロパ
ティへの有効な参照であるかどうかが検証されます。エラーが発生するとページ
を保存できません。
単一の入力項目を使用する <apex:form> コンポーネント
<apex:inputField> タグが表示できない唯一の項目は、Apex で記述されたカスタム
コントローラクラスのメンバー変数として定義された項目です。それらの変数で使用
するデータを収集するには、代わりに <apex:inputCheckbox>、
<apex:inputHidden>、<apex:inputSecret>、<apex:inputText>、または
<apex:inputTextarea> タグを使用します。
210
第 14 章 Visualforce
入力項目の表示ラベルの追加とカスタマイズ
Visualforce 入力コンポーネントおよびいくつかの出力コンポーネントは、
<apex:pageBlockSection> コンポーネント内で使用されている場合、項目のフォー
ム表示ラベルを自動的に表示します。標準またはカスタムオブジェクト項目に対応付
けられているコンポーネントでは、表示されるラベルは、デフォルトでは、オブジェ
クト項目表示ラベルです。このデフォルト値を上書きする場合、およびオブジェクト
項目に直接対応付けされていないコンポーネントの場合は、コンポーネントの label
属性を使用して表示ラベルを設定できます。次に例を示します。
<apex:page standardController="Contact">
<apex:form>
<apex:pageBlock title="Quick Edit: {!Contact.Name}">
<apex:pageBlockSection title="Contact Details" columns="1">
<apex:inputField value="{!Contact.Phone}"/>
<apex:outputField value="{!Contact.MobilePhone}"
label="Mobile #"/>
<apex:inputText value="{!Contact.Email}"
label="{!Contact.FirstName + '’s Email'}"/>
</apex:pageBlockSection>
<apex:pageBlockButtons >
<apex:commandButton action="{!save}" value="Save"/>
</apex:pageBlockButtons>
</apex:pageBlock>
</apex:form>
211
第 14 章 Visualforce
</apex:page>
メモ: このページで取引先責任者データを表示する場合、有効な取引先責任者レ
コードの ID をページの URL のクエリパラメータとして指定する必要があります。
たとえば、
https://Salesforce_instance/apex/myPage?id=003D000000Q513R
「Visualforce による項目値の表示」 (ページ 202)には、レコードの ID の取得につい
ての詳細が記載されています。
label 属性には、文字列、または評価結果が文字列になる式を指定できます。label
を空の文字列に設定すると、その項目のフォーム表示ラベルは表示されません。
label 属性は次の Visualforce コンポーネントで設定できます。
• <apex:inputCheckbox>
• <apex:inputField>
• <apex:inputSecret>
• <apex:inputText>
• <apex:inputTextarea>
• <apex:outputField>
• <apex:outputText>
212
第 14 章 Visualforce
• <apex:selectCheckboxes>
• <apex:selectList>
• <apex:selectRadio>
カスタム表示ラベルとエラーメッセージ
label 属性が設定されている場合、項目が必須であるときまたは一意になっている必
要があるときなどに、この属性はコンポーネントレベルのエラーメッセージで使用さ
れます。カスタム表示ラベルはカスタムエラーメッセージでは使用されません。デ
フォルトのオブジェクト項目の表示ラベルが代わりに使用されます。label 属性を空
の文字列に設定すると、デフォルトのオブジェクト項目の表示ラベルはすべてのエ
ラーメッセージで使用されます。
ページへの連動項目の追加
連動項目では、Visualforceページに表示される項目の値を絞り込むことができます。連
動項目は、条件を決定する制御項目と、値が条件で絞り込まれた連動項目の 2 つで構
成されます。連動項目は、選択リスト、複数選択リスト、ラジオボタン、およびチェッ
クボックスなどの項目の値を動的に絞り込むことができます。連動選択リストは、
Salesforce API バージョン 19.0 以降を使用する Visualforce ページでのみ表示できます。詳
細は、Salesforce オンラインヘルプの「連動選択リストについて」を参照してくださ
い。
この例では、連動選択リスト (サブカテゴリ) をVisualforceページに追加します。まず、
カスタム選択リストを作成します。
1. [設定] から、[カスタマイズ] > [取引先] > [項目] をクリックします。
2. ページの [カスタム項目 & リレーション] セクションにある [新規] をクリックし
ます。
3. [選択リスト] を選択し、[次へ] をクリックします。
4. [項目の表示ラベル] に「サブカテゴリ」と入力します。
5. 値のリストに次の語句を入力します。
• りんご農場
• ケーブル
• とうもろこし畑
213
第 14 章 Visualforce
• インターネット
• ラジオ
• テレビ
• ワイナリー
6. [次へ] を 2 回クリックし、[保存] をクリックします。
サブカテゴリの項目の連動関係を定義する手順は、次のとおりです。
1. [設定] から、[カスタマイズ] > [取引先] > [項目] をクリックします。
2. [項目の連動関係] をクリックします。
3. [新規] をクリックします。
4. 制御項目として [業種] を、連動項目として [サブカテゴリ] を選択します。
5. [次へ] をクリックします。
6. 制御項目の各値 (業種) は、一番上の行にリストされており、連動項目の各値 (サ
ブカテゴリ) はその下の列に表示されます。この画像に一致するように、項目
の連動関係を設定します。
サブカテゴリの項目の連動関係マトリックス
上記に表示されていない他の [業種] の種別は無視できます。
7. [保存] をクリックします。
次のような dependentPicklists という Visualforce ページを作成します。
<apex:page standardController="Account">
<apex:form >
<apex:pageBlock mode="edit">
<apex:pageBlockButtons >
214
第 14 章 Visualforce
<apex:commandButton action="{!save}" value="Save"/>
</apex:pageBlockButtons>
<apex:pageBlockSection title="Dependent Picklists"
columns="2">
<apex:inputField value="{!account.industry}"/>
<apex:inputField value="{!account.subcategories__c}"/>
</apex:pageBlockSection>
</apex:pageBlock>
</apex:form>
</apex:page>
[業種] 選択リストから [農業] を選択すると、サブカテゴリ選択リストには [りんご農
場]、[とうもろこし畑]、および [ワイナリー] が表示されます。[通信] を選択すると、
[サブカテゴリ] 選択リストには、上記で定義した すべての通信の種別の項目が表示さ
れます。
連動選択リストの考慮事項
Visualforce ページで連動選択リストを使用するときは、次の点に留意してください。
• 選択リスト、複数選択リスト、ラジオボタン、およびチェックボックスなどのさ
まざまな項目の種別で制御項目と連動項目を混在させて使用できます。
• 1 つのページに使用できる連動選択リストのペアは最大 10 個です。これはすべて
のオブジェクトで合計されます。したがって、Account オブジェクトに 5 つの連動
選択リストを使用し、Contact オブジェクトに 5 つの連動選択リストを使用できま
すが、それ以上使用することはできません。ただし、連動選択リストの同じペア
を <apex:repeat> などの反復タグで繰り返し使用することができ、この場合、
制限との関係では 1 回のみカウントされます。
• ページを表示しているユーザに制御項目への参照のみのアクセス権がある場合、
連動選択リストが期待どおりに動作しないことがあります。この場合、連動選択
215
第 14 章 Visualforce
リストには、参照のみの値で絞り込まれる代わりに、選択可能なすべての値が表
示されてしまいます。これは Visualforce の既知の制限です。
• 連動選択リストを使用する場合、ページに制御項目を含める必要があります。ペー
ジに制御項目が含まれていない場合、ページを表示するときにランタイムエラー
が発生します。
• インライン編集を有効にした項目と同じ連動関係グループの通常の入力項目を混
合しないでください。たとえば、制御項目の標準の入力項目とインライン編集を
有効にした連動項目は混合しないでください。
<apex:page standardController="Account">
<apex:form>
<!-- Don't mix a standard input field... -->
<apex:inputField value="{!account.Controlling__c}"/>
<apex:outputField value="{!account.Dependent__c}">
<!-- ...with an inline-edit enabled dependent field -->
<apex:inlineEditSupport event="ondblClick" />
</apex:outputField>
</apex:form>
</apex:page>
• インライン編集を有効にした連動選択リストと Ajax スタイルの部分ページ更新を
組み合わせる場合は、相互に連動または制御関係にあるすべての項目を 1 つのグ
ループとして更新します。項目を個別に更新することはお勧めしません。元に戻
す動作またはやり直す動作の一貫性がなくなる場合があります。インライン編集
を有効にした連動選択リストがあるフォームを部分更新する方法の推奨例を次に
示します。
<apex:form>
<!-- other form elements ... -->
216
第 14 章 Visualforce
<apex:outputPanel id="locationPicker">
<apex:outputField value="{!Location.country}">
<apex:inlineEditSupport event="ondblClick" />
</apex:outputField>
<apex:outputField value="{!Location.state}">
<apex:inlineEditSupport event="ondblClick" />
</apex:outputField>
<apex:outputField value="{!Location.city}">
<apex:inlineEditSupport event="ondblClick" />
</apex:outputField>
</apex:outputPanel>
<!-- ... -->
<apex:commandButton value="Refresh Picklists"
reRender="locationPicker" />
</apex:form>
インライン編集を有効にした選択リストのすべてが <apex:outputPanel> コン
ポーネントでラップされています。<apex:outputPanel> は
<apex:commandButton> アクションメソッドが起動すると表示されます。
Visualforce ダッシュボードコンポーネントの作成
Visualforce ページは、ダッシュボードコンポーネントとして使用できます。ダッシュ
ボードでは、ソースレポートから得たデータを、グラフ、ゲージ、テーブル、総計
値、または Visualforce ページなど、視覚化されたコンポーネントとして表示します。
コンポーネントは、組織の主要な総計値のスナップショットおよびパフォーマンスの
217
第 14 章 Visualforce
指標を提供します。各ダッシュボードには、最大 20 個のコンポーネントを含めること
ができます。
標準コントローラを使用する Visualforce ページをダッシュボードで使用することはで
きません。Visualforce ページをダッシュボードで使用するには、そのページがコント
ローラを含んでいないか、1 つのカスタムコントローラを使用しているか、または
StandardSetController クラスにバインドされたページを参照している必要があります。
Visualforceページは、これらの要件を満たさない場合、ダッシュボードコンポーネント
の [Visualforce ページ] ドロップダウンリストにオプションとして表示されませ
ん。
VFDashboard という Visualforce ページを作成します。次のマークアップは、標準リス
トコントローラを使用し、ダッシュボード内で使用できる Visualforce ページの例を示
しています。このページは、組織に関連付けられたケースのリストを表示します。
<apex:page standardController="Case" recordSetvar="cases">
<apex:pageBlock>
<apex:form id="theForm">
<apex:panelGrid columns="2">
<apex:outputLabel value="View:"/>
<apex:selectList value="{!filterId}" size="1">
<apex:actionSupport event="onchange"
rerender="list"/>
<apex:selectOptions value="{!listviewoptions}"/>
</apex:selectList>
</apex:panelGrid>
<apex:pageBlockSection>
<apex:dataList var="c" value="{!cases}" id="list">
{!c.subject}
</apex:dataList>
218
第 14 章 Visualforce
</apex:pageBlockSection>
</apex:form>
</apex:pageBlock>
</apex:page>
このVisualforceページを使用するダッシュボードを作成する手順は、次のとおりです。
1. ダッシュボードを表示し、[編集] をクリックします。
2. 任意の列の上部にある [コンポーネントの追加] をクリックします。
3. コンポーネントの種類として [Visualforce ページ] を選択します。
4. 必要に応じて、ダッシュボードコンポーネントの上部に表示するヘッダーを入
力します。
5. 必要に応じて、ダッシュボードコンポーネントの下部に表示するフッターを入
力します。
6. [Visualforce ページ] ドロップダウンリストから、VFDash を選択します。
7. [保存] をクリックします。
ダッシュボードで実行する Visualforce ページのサンプル
カスタムリストコントローラを使用する、より複雑な例については、「高度なVisualforce
ダッシュボードコンポーネント」を参照してください。
219
第 14 章 Visualforce
ベストプラクティス
このセクションで説明するベストプラクティスを考慮してください。
Visualforce のパフォーマンス向上のためのベストプラ
クティス
Visualforce は、標準の Salesforce ページの機能、動作およびパフォーマンスに合わせる機
能を開発者に提供するために設計されました。遅延、予期しない動作や、その他の問
題 (特にVisualforceに関するもの) がある場合は、いくつかの対処法を実行することによ
り、操作性を改善できるだけでなく、コーディングの改善にも役立てることができま
す。
まず、次を確認して、Visualforce に問題があるかどうかを特定します。
• 予測される Visualforce の機能を他のマシンや他のブラウザを使用してテストし、そ
の問題が 1 台のユーザのコンピュータに限らないことを確認する。
• 他の Salesforce ページの読み込み時間を確認して、読み込みに時間がかかることが
ネットワーク上の問題ではないことを確認する。他のページの読み込みにも時間
がかかる場合は、Salesforceにおける帯域幅や待ち時間の問題が原因である可能性が
あります。Salesforce サーバの状況を確認するには、trust.salesforce.comを参照してく
ださい。また、ネットワーク接続の状況をチェックして、適切に機能しているか
どうかを確認する必要があります。
• JavaScript および CSS の縮小、Web 画像の最適化、できる限り iframe の使用を避ける
など、一般的な Web 設計のベストプラクティスに従っていることを確認する。
• 開発者コンソールを使用して、要求をステップごとに実行し、要求内のどの項目
がシステムリソースを最も消費したかを調べる。Salesforceオンラインヘルプの「開
発者コンソールの使用」を参照してください。
次のリストは、よく発生する Visualforce のパフォーマンス上の問題と解決策を示した
ものです。
ビューステートのサイズ
Visualforce ページのビューステートのサイズは、135 KB 未満である必要があります。
ビューステートのサイズを縮小することにより、ページをより迅速に読み込み、
表示が停止する頻度を削減します。
220
第 14 章 Visualforce
開発モードフッターの [ビューステート] タブを使用し、次の対処法を実行すると、
ビューステートのパフォーマンスを監視できます。
• 状態の維持に不可欠ではなく、ページの更新時にも不要な変数には、Apexコン
トローラで transient キーワードを使用する。
• ビューステートの大部分をコントローラまたはコントローラ拡張で使用されて
いるオブジェクトから取得していることが分かった場合は、Visualforceページに
関連するデータのみを戻すように SOQL コールの絞り込みを検討する。
• ビューステートが大規模なコンポーネントツリーの影響を受けている場合は、
ページが依存しているコンポーネント数の削減を試みる。
読み込み時間
サイズが大きいページは読み込み時間に直接影響します。Visualforce ページの読み
込み時間を改善するには、次の対処法を実行します。
• アイコンの画像など頻繁にアクセスするデータをキャッシュする。
• Apex コントローラの getter メソッドで SOQL クエリを使用しない。
• 次の対処法を実行して、ページ上に表示するレコード件数を削減する。
– Apex コントローラで SOQL コールから返されるデータを制限する。たとえ
ば、WHERE 句で AND ステートメントを使用したり、null の結果を削除し
たりします。
– リストコントローラでページネーションを活用して、ページあたりの表示
レコード件数を削減する。
• Apex オブジェクトを遅延読み込みして要求時間を削減する。
• <apex:includeScript> タグ外に JavaScript を移動し、<apex:page> 終了タグ
のすぐ前の <script> タグに配置することを検討する。
<apex:includeScript> タグは、JavaScript を閉じ要素 <head> のすぐ前に配
置します。つまり、Visualforceではページ上のその他のコンテンツの前に JavaScript
が読み込まれます。ただし、ページにマイナスの影響を及ぼさない確信がある
場合は、JavaScript をページ最下部に移動するだけにしてください。たとえば、
document.write またはイベントハンドラを必要とする JavaScript コードスニ
ペットは、<head> 要素に配置したままにする必要があります。
どの場合でも、Visualforce ページは 15 MB 未満である必要があります。
221
第 14 章 Visualforce
複数の同時要求
同時要求は他の保留中のタスクをブロックする可能性のある実行に長時間かかる
タスクです。これらの遅延を短縮する対処法は、次のとおりです。
• <apex:actionPoller> で使用する action メソッドを軽量にする。これは、
<apex:actionPoller> からコールされる action メソッドで、DML の実行、外
部サービスコール、およびリソースを大量に消費する他の操作を回避するため
のベストプラクティスです。指定した間隔で <apex:actionPoller> から繰
り返しコールされる action メソッドの影響を考慮します。特に、広範囲にわたっ
て配布されたり、継続的に開かれたりするページで使用する場合には注意が必
要です。
• Visualforce ページから Apex をコールする間隔を延長する。たとえば、
<apex:actionPoller> コンポーネントの使用時は、interval 属性を 15 では
なく 30 秒に調整します。
• Ajax を使用して不要なロジックを非同期コードブロックに移動する。
クエリおよびセキュリティ
Apex コントローラの作成時に with sharing キーワードを使用して 1 人のユーザ
のデータセットを表示するだけで、SOQL クエリを向上できる可能性があります。
ページに項目値をすべて表示する
ページに大きなテキストエリア項目など多くの項目があり、他のエンティティと
の主従関係がある場合、Visualforce ページに返されるデータのサイズに関する制限
およびバッチ制限のためデータをすべて表示できないことがあります。ページに
は、次の警告が表示されます。「You requested too many fields to display. Consider removing
some to prevent field values from being dropped from the display. (要求した項目が多すぎて表
示できません。項目値をすべて表示するには項目値の一部を削除することを検討
してください。)」
ページに項目値をすべて表示するには、一部の項目を削除して返されるデータ量
を削減します。または、コントローラ拡張を独自に作成して、関連リストに表示
される子レコードをクエリします。
222
第 14 章 Visualforce
コンポーネント ID へのアクセスのベストプラクティ
ス
JavaScript または他の Web 対応言語で Visualforce コンポーネントを参照するには、そのコ
ンポーネントの id 属性の値を指定する必要があります。DOM ID はコンポーネントの
id 属性とその要素を含むすべてのコンポーネントの id 属性の組み合わせで構成さ
れます。
$Component グローバル変数を使用すると、Visualforce コンポーネント用に生成される
DOM ID の参照が簡略化され、ページ構造全体での連動関係の一部が削減されます。特
定の Visualforce コンポーネントの DOM ID を参照するには、ページのコンポーネント階
層の各レベルを区切るドット表記を使用して、コンポーネントのパス指定子を
$Component に追加します。たとえば、Visualforceコンポーネント階層の同じレベルに
あるコンポーネントを参照するには $Component.itemId を使用し、完全なコンポー
ネントパスを指定するには $Component.grandparentId.parentId.itemId を使用し
ます。
$Component パス指定子は、コンポーネント階層と次のように照合されます。
• $Component が使用されているコンポーネント階層の現在のレベルでまず照合さ
れます。
• 次に、一致が検出されるか、コンポーネント階層の最上位レベルに達するまで、
コンポーネント階層の各上位レベルが照合されます。
バックトラッキングはないため、ID の照合で上に移動してから下に戻る必要がある場
合は、一致しません。
次の例に、$Component のいくつかの使用方法を示します。
<apex:page >
<style>
.clicker { border: 1px solid #999; cursor: pointer;
margin: .5em; padding: 1em; width: 10em; text-align: center;
}
</style>
223
第 14 章 Visualforce
<apex:form id="theForm">
<apex:pageBlock id="thePageBlock" title="Targeting IDs with
$Component">
<apex:pageBlockSection id="theSection">
<apex:pageBlockSectionItem id="theSectionItem">
All the alerts refer to this component.
<p>The full DOM ID resembles something like
this:<br/>
j_id0:theForm:thePageBlock:theSection:theSectionItem</p>
</apex:pageBlockSectionItem>
<!-- Works because this outputPanel has a parent in
common
with "theSectionItem" component -->
<apex:outputPanel layout="block" styleClass="clicker"
onclick="alert('{!$Component.theSectionItem}');">
First click here
</apex:outputPanel>
</apex:pageBlockSection>
224
第 14 章 Visualforce
<apex:pageBlockButtons id="theButtons" location="bottom">
<!-- Works because this outputPanel has a grandparent
("theSection")
in common with "theSectionItem" -->
<apex:outputPanel layout="block" styleClass="clicker"
onclick="alert('{!$Component.theSection.theSectionItem}');">
Second click here
</apex:outputPanel>
<!-- Works because this outputPanel has a distant
ancestor ("theForm")
in common with "theSectionItem" -->
<apex:outputPanel layout="block" styleClass="clicker"
onclick="alert('
{!$Component.theForm.thePageBlock.theSection.theSectionItem}');">
Third click here
</apex:outputPanel>
</apex:pageBlockButtons>
</apex:pageBlock>
225
第 14 章 Visualforce
<!-- Works because this outputPanel is a sibling to
"thePageBlock",
and specifies the complete ID path from that sibling -->
<apex:outputPanel layout="block" styleClass="clicker"
onclick="alert('{!$Component.thePageBlock.theSection.theSectionItem}');">
Fourth click here
</apex:outputPanel>
<hr/>
<!-- Won't work because this outputPanel doesn't provide a
path
that includes a sibling or common ancestor -->
<apex:outputPanel layout="block" styleClass="clicker"
onclick="alert('{!$Component.theSection.theSectionItem}');">
This won't work
</apex:outputPanel>
<!-- Won't work because this outputPanel doesn't provide a
path
that includes a sibling or common ancestor -->
226
第 14 章 Visualforce
<apex:outputPanel layout="block" styleClass="clicker"
onclick="alert('{!$Component.theSectionItem}');">
Won't work either
</apex:outputPanel>
</apex:form>
</apex:page>
一意の ID の使用
コンポーネント id はページの各階層セグメント内で一意である必要があります。た
だしSalesforceでは、参照する必要があるすべてのコンポーネント、およびその参照に
必要なコンポーネント階層の上位コンポーネントに対して、ページで一意の id を使
用することをお勧めします。
たとえば、1 つのページに 2 つのデータテーブルがあるとします。両方のデータテー
ブルが同じページブロック内に指定されている場合は、両方のデータテーブルの id
属性が一意である必要があります。それぞれが別のページブロックに指定されている
場合は、同じコンポーネント id を付与することができます。ただし、この場合、特
定のデータテーブルを参照できる唯一の方法として、すべてのコンポーネントに id
を割り当ててから、Visualforceで自動的に参照するのではなく、コンポーネント階層を
使用してデータテーブルのコンポーネントを参照する必要があります。また、ページ
階層に変更があると、プログラムが機能しません。
コンポーネント ID での反復
テーブル、リストなどの一部のコンポーネントでは、レコードのコレクションの反復
をサポートしています。これらのタイプのコンポーネントに ID を割り当てると、コン
ポーネントの各反復に、最初の ID に基づいて一意の「複合 ID」が割り当てられます。
227
第 14 章 Visualforce
たとえば、次のページには theTable に設定された ID を含むデータテーブルがあり
ます。
<apex:page standardController="Account" recordSetVar="accounts"
id="thePage">
<apex:dataTable value="{!accounts}" var="account" id="theTable">
<apex:column id="firstColumn">
<apex:outputText value="{!account.name}"/>
</apex:column>
<apex:column id="secondColumn">
<apex:outputText value="{!account.owner.name}"/>
</apex:column>
</apex:dataTable>
</apex:page>
このページを表示すると、<apex:dataTable> コンポーネントは次の HTML になりま
す。
<table id="thePage:theTable" border="0" cellpadding="0" cellspacing="0">
<colgroup span="2"/>
<tbody>
<tr class="">
<td id="thePage:theTable:0:firstColumn">
<span id="thePage:theTable:0:accountName">Burlington
Textiles</span>
</td>
<td id="thePage:theTable:0:secondColumn">
228
第 14 章 Visualforce
<span id="thePage:theTable:0:accountOwner">Vforce
Developer</span>
</td>
</tr>
<tr class="">
<td id="thePage:theTable:1:firstColumn">
<span id="thePage:theTable:1:accountName">Dickenson</span>
</td>
<td id="thePage:theTable:1:secondColumn">
<span id="thePage:theTable:1:accountOwner">Vforce
Developer</span>
</td>
</tr>
</table>
各テーブルセルには、そのセルを含むコンポーネントの ID の値に基づいて設定される
一意の ID があります。最初の行の最初のテーブルセルの ID は
thePage:theTable:0:firstColumn、最初の行の 2 番目のセルの ID は
thePage:theTable:0:secondColumn、2 行目の最初のセルの ID は
thePage:theTable:1:firstColumn です (以下同様)。
列のすべてのエントリを参照するには、テーブルの行を反復して、列の形式に従った
ID を含む各 <td> 要素を参照する必要があります。
同じタイプの ID の生成がテーブルセル内の要素に対して実行されます。たとえば、最
初の行の取引先名は、ID が thePage:theTable:0:accountName である span とし
て生成されます。ID にはその ID がある列の ID の値は含まれません。
229
第 14 章 Visualforce
静的リソースのベストプラクティス
<apex:page> の action 属性を使用した静的リソースのコンテンツの表示
<apex:page> コンポーネントのaction属性を使用して、Visualforce ページから静
的リソースにリダイレクトできます。この機能を使用すれば、機能豊富なカスタ
ムヘルプを Visualforce ページに追加できます。たとえば、ユーザを PDF にリダイレ
クトするとします。
1. PDF を customhelp という名前で静的リソースとしてアップロードします。
2. 次のページを作成します。
<apex:page sidebar="false" showHeader="false"
standardStylesheets="false"
action="{!URLFOR($Resource.customhelp)}">
</apex:page>
静的リソース参照は、URLFOR 関数でラップされています。そうしないと、ページ
は適切にリダイレクトされません。
このリダイレクトは PDF ファイルに限りません。静的リソースのコンテンツにペー
ジをリダイレクトすることもできます。たとえば、JavaScript、画像、およびその他
のマルチメディアファイルを組み合わせた多数の HTML ファイルで構成されるヘル
プシステム全体を含む静的リソースを作成できます。エントリポイントが 1 つある
限り、リダイレクトは機能します。次に例を示します。
1. ヘルプコンテンツを含む zip ファイルを作成します。
2. zip ファイルを customhelpsystem という名前で静的リソースとしてアップ
ロードします。
3. 次のページを作成します。
<apex:page sidebar="false" showHeader="false"
standardStylesheets="false"
action="{!URLFOR($Resource.customhelpsystem, 'index.htm')}">
</apex:page>
230
第 14 章 Visualforce
ユーザがページにアクセスすると、静的リソースの index.htm ファイルが表示さ
れます。
コントローラおよびコントローラ拡張のためのベスト
プラクティス
コントローラでの共有ルールの適用
他の Apex クラスと同様に、カスタムコントローラおよびコントローラ拡張はシス
テムモードで実行されます。
通常、コントローラまたはコントローラ拡張ではユーザの組織の共有設定、ロー
ル階層および共有ルールを遵守する必要があります。これは、クラス定義で with
sharing キーワードを使用することにより実行できます。詳細は、『Force.comApex
コード開発者ガイド』の「with sharing または without sharing キーワード
の使用」を参照してください。
メモ: コントローラ拡張が標準コントローラを拡張する場合、標準コントロー
ラのロジックはシステムモードで実行されません。代わりに、ユーザモード
で実行されます。このモードでは現在のユーザの権限、項目レベルのセキュ
リティ、共有ルールが適用されます。
コントローラのコンストラクタを setter メソッドの前に評価
コンストラクタの前に評価される setter メソッドには依存しないでください。たと
えば、次のコンポーネントでは、コンポーネントのコントローラがコンストラク
タメソッドの前にコールされる selectedValue の setter に依存しています。
<apex:component controller="CustCmpCtrl">
<apex:attribute name="value" description=""
type="String" required="true"
assignTo="{!selectedValue}">
</apex:attribute>
//...
//...
231
第 14 章 Visualforce
</apex:component>
public class CustCmpCtrl {
// Constructor method
public CustCmpCtrl() {
if (selectedValue != null) {
EditMode = true;
}
}
private Boolean EditMode = false;
// Setter method
public String selectedValue { get;set; }
}
コンストラクタが setter の前にコールされるため、コンストラクタがコールされる
と selectedValue は常に null になります。このため、EditMode が true に設定さ
れることはありません。
メソッドは複数回評価される場合がある (副次的影響を使用しない)
controller、action 属性および式のメソッドを含むメソッドは複数回コールできます。
コントローラまたはコントローラ拡張でカスタムメソッドを作成するときの評価
の順序または副次的影響には依存しないでください。
232
第 14 章 Visualforce
リソース
Visualforce に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• Visualforce 開発者ガイド
• Visualforce 早見表
• Visualforce ワークブック
• Visualforce 開発フォーラム
233
第 15 章
Force.com Canvas
Force.com Canvas は、アプリケーションをキャンバスアプリケーションとして公開する
ために使用できるツールと JavaScript API のセットです。
Force.com Canvas を使用するケース
Force.com Canvas を使用すると、サードパーティのアプリケーションを Salesforce に簡単
に統合することができます。つまりこれを活用することで、新しいアプリケーション
または既存のアプリケーションをSalesforceの一部としてユーザに提供できるようにな
ります。外部アプリケーションを再設計して再統合する代わりに、これらのツールを
使用して、Force.com Canvas 内の独自技術を統合できるようになりました。キャンバス
アプリケーションとして公開するサードパーティアプリケーションは、どの言語でも
作成できます。唯一の要件として、アプリケーションに安全な URL (HTTPS) がある必要
があります。
Force.com Canvas が実装される一般的なシナリオとして、大まかに次の 2 つの例があり
ます。
• アプリケーション統合 — クラウドアプリケーションを作成するパートナー、シス
テムインテグレータ、または顧客で、Salesforceを使用してこれらのアプリケーショ
ンを統合したいと思っている場合。
• アプリケーション合理化/エンタープライズデスクトップ — Salesforce のほかにも
ユーザがアクセスする多数の既存のアプリケーションを持つ大規模組織に属して
いて、ユーザが 1 つの場所ですべてのタスクを完了できるように、これらのアプリ
ケーションを Salesforce に統合したいと思っている場合。
サポート対象のエディションとプラットフォーム
Force.com Canvas では、次の Salesforce エディションをサポートしています。
235
第 15 章 Force.com Canvas
エディション
キャンバスアプリ
ケーションの作成
キャンバスアプリ
ケーションの公開
キャンバスアプリ
ケーションのインス
トール
Group
○*
×
○*
Professional
○*
×
○*
Enterprise
○
×
○
Unlimited
○
×
○
Performance
○
×
○
Developer
○
○
○
* キャンバスアプリケーションを指定した位置に表示するには、Professional Edition 組織
で Force.com Canvas が有効化されている必要があります。
Force.com Canvas では、次のブラウザがサポートされます。
• Mozilla® Firefox® (推奨)
• Google Chrome™
• Microsoft® Internet Explorer® バージョン 8、 9、10 (互換モードは必ず無効にしてくださ
い)、および 11
• Apple® Safari® ([Cookie をブロック] の設定が [しない] に設定されていることを確認して
ください)
アプリケーションでセッション Cookie が使用される場合、サードパーティの Cookie を
許可するように P3P ヘッダーを設定するか、すべてのセッション Cookie を許可するよ
うにブラウザの設定を変更する必要が生じることがあります。
キャンバスアプリケーションの作成、およびキャンバスアプリケーションのプレビュー
アでの表示には、次の Salesforce ユーザ権限が必要です。
• アプリケーションのカスタマイズ
• すべてのデータの編集
236
第 15 章 Force.com Canvas
クイックスタート
ここでは、Heroku のクイックスタートを使用して、Force.com Canvas の使用を簡単に開
始する方法を説明します。Heroku のクイックスタートでは、選択したテンプレートに
応じて Java または Ruby で「hello world」アプリケーションが Heroku に作成されます。
同時に、対応するキャンバスアプリケーションが Salesforce に作成されます。
Heroku アプリケーションは、Force.com Canvas SDK をコールする「hello world」Web ページ
です。これにより、現在のユーザに関する情報を表示したり、現在のユーザの Chatter
フィードを投稿したりできます。
前提条件
クイックスタートの手順を実行するには、適切なアクセス権とツールが必要です。
• Developer Edition 組織にアクセスします。
まだ Force.com 開発者コミュニティのメンバーでない場合、
developer.salesforce.com/signup にアクセスし、Developer Edition 組織のサイ
ンアップの説明に従ってください。すでに Enterprise Edition、Unlimited Edition、また
は Performance Edition を所有している場合でも、組織の使用中のデータを保護するた
めに、サンプルデータに対するソリューションの開発、ステージングおよびテス
トには Developer Edition を使用します。これは、特に、(データをただ参照するだけ
のアプリケーションに対し) データを挿入、更新または削除するアプリケーション
の場合に該当します。
既存の Developer Edition 組織があるにもかかわらず [キャンバスアプリケーションの
プレビューア] メニュー項目が [設定] に表示されない場合、Salesforce にお問い合わ
せください。
• 「アプリケーションのカスタマイズ」および「すべてのデータの編集」ユーザ権
限。ほとんどの場合、管理者にはすでにこれらの権限があります。管理者以外の
場合、キャンバスアプリケーションのプレビューアを表示してキャンバスアプリ
ケーションを作成できるようにこれらの権限を追加する必要があります。
• Heroku アカウント。https://api.heroku.com/signup に移動し、Heroku アカウ
ントを作成します。
237
第 15 章 Force.com Canvas
アプリケーションの作成
ここでは、Heroku「hello world」アプリケーションおよびそれに関連付けられたキャン
バスアプリケーションを Salesforce 組織で作成する手順を説明します。
1. Salesforce の [設定] で [キャンバスアプリケーションのプレビューア] をクリック
します。
2. [Heroku のクイックスタート] をクリックします。
3. [テンプレート] 項目で、[Java – クイックスタートテンプレート] を選択します。
4. [キャンバスアプリケーション名] 項目に、30 文字までの一意の名前を入力しま
す。
5. [Heroku アプリケーション名] 項目に、文字で始まり、小文字、数字、ダッ
シュのみを含む 30 文字までの一意の名前を入力します。newappName は、すべ
ての Heroku アプリケーションで一意である必要があります。この名前は、
newappName.herokuapp.com のようにアプリケーションの URL の一部になり
ます。
6. [認証種別] 項目で、[ユーザ名/パスワード] を選択します。
7. [Heroku ユーザ名] 項目に、Heroku にログインするために使用するアカウント
のユーザ名を入力します。通常、これはメールアドレスになります。Heroku ア
プリケーションは、このユーザのログイン情報に基づいて作成されます。
メモ: この項目には、最大で 30 文字を含めることができます。Heroku ユー
ザ名が 30 文字を超える場合、アカウントに関連付けられた API キーを使
用する必要があります。この値は、Heroku [私の取引先] ページで確認で
きます。
8. [Heroku パスワード] 項目に、Heroku にログインするために使用するアカウン
トのパスワードを入力します。
ヒント: Heroku アカウントのユーザ名とパスワードを使用する代わりに、
アカウントの関連付けられている API キーを使用することもできます。
この値は、Heroku [取引先] ページで確認できます。または、Heroku OAuth
を介して Heroku OAuth フローを開始するか、現在 Heroku にログインして
いる場合は Heroku トークンを使用することができます。
238
第 15 章 Force.com Canvas
9. [作成] をクリックします。アプリケーションが左側のナビゲーションペインに
表示されます。
「Heroku コピーである REST サービスへの POST を実行中にエラーが発生しました:
読み取りタイムアウト。」のようなエラーが表示された場合、Heroku への接続
操作がタイムアウトしたことを意味します。http://status.heroku.com で
Heroku の状況を確認できます。
10. 左側にある新しいアプリケーションへのリンクをクリックします。
アプリケーションが表示され、Hello User.FullName というメッセージと現
在のユーザに関するその他の情報が表示されます。
キャンバスアプリケーションが作成されました。「アプリケーションの場所の設定」
の手順に従って、アプリケーションを表示できる場所を設定するまで、キャンバスア
プリケーションを表示できる場所はキャンバスアプリケーションのプレビューアに限
定されます。この手順では、各組織にアプリケーションをインストールした後で、
ユーザがアプリケーションを参照する場所を定義します。
Heroku のクイックスタートにより、バックグラウンドでキャンバスアプリケーション
の [許可されているユーザ] が設定されます。これには、システム管理者が承認した
ユーザとプロファイルが含まれます。たとえば、ユーザプロファイルがシステム管理
者の場合、そのプロファイルが作成したキャンバスアプリケーションに追加され、そ
のプロファイルが設定された任意のユーザがキャンバスアプリケーションにアクセス
できるようになります。
アプリケーションの場所の設定
ここでは、Salesforce のユーザにキャンバスアプリケーションを表示する場所を指定す
る手順を説明します。
1. Salesforce アプリケーションで、[設定] から [作成] > [アプリケーション] をクリッ
クします。
2. [接続アプリケーション] 関連リストで、作成したアプリケーションをクリック
して [編集] をクリックします。
3. [キャンバスアプリケーション設定] セクションの [場所] 項目で、キャンバスア
プリケーションをユーザに表示する場所を選択します。このステップでは、
[[Chatter] タブ] を選択します。
239
第 15 章 Force.com Canvas
• Chatter フィード — キャンバスアプリケーションをフィードに表示します。
このオプションが選択されている場合、CanvasPost フィード項目を作成し、
現在のユーザがキャンバスアプリケーションにアクセスできるようにする
必要があります。
• [Chatter] タブ: キャンバスアプリケーションを Chatter タブのアプリケーショ
ンナビゲーションリストに表示します。このオプションを選択すると、キャ
ンバスアプリケーションはその場所に自動的に表示されます。
• コンソール — キャンバスアプリケーションをSalesforce コンソールのフッター
またはサイドバーに表示します。このオプションを選択した場合、キャン
バスアプリケーションをカスタムコンソールコンポーネントとして追加し
て、コンソールのどこにキャンバスアプリケーションを表示するのかを選
択する必要があります。
• レイアウトおよびモバイルカード — キャンバスアプリケーションをページ
レイアウトまたはモバイルカードに表示できます。このオプションを選択
した場合、ページレイアウトに追加してキャンバスアプリケーションが表
示される場所を選択します。
• モバイルナビゲーション — キャンバスアプリケーションをSalesforce1のナビ
ゲーションメニューからアクセス可能にします。
• Open CTI — キャンバスアプリケーションを通話制御ツールに表示します。
このオプションを選択した場合、キャンバスアプリケーションを表示する
にはコールセンターの定義ファイルにキャンバスアプリケーションを指定
する必要があります。
• パブリッシャー — キャンバスアプリケーションを Chatter パブリッシャーお
よび Salesforce1 アクションバーに表示します。このオプションが選択されて
いる場合は、キャンバスカスタムアクションを作成して、グローバルパブ
リッシャーレイアウトまたはオブジェクトのページレイアウトに追加する
必要もあります。
• Visualforce ページ — キャンバスアプリケーションを Visualforce ページに表示
できます。Visualforce ページにキャンバスアプリケーションを公開するため
に <apex:canvasApp> コンポーネントを追加する場合、キャンバスアプリ
ケーションの表示場所にこの場所を必ず選択してください。これ以外の場
所を選択するとエラーになります。
4. [保存] をクリックします。
240
第 15 章 Force.com Canvas
[[Chatter] タブ] を選択したため、Chatter タブの左側のナビゲーションペインに
キャンバスアプリケーションが表示されます。
ベストプラクティス
このセクションで説明するベストプラクティスを考慮してください。
Force.com Canvas SDK の参照
Force.com Canvas SDK は GitHub から入手できます。また、キャンバスアプリケーション
から参照するには次の 2 つの方法があります。
• SDK を自分の Web サーバでホストして、そこからアクセスする
• Salesforce サーバにホストされた SDK にアクセスする
SDK を自分の Web サーバでホストする場合の include ステートメントの例は次のとおり
です。
<script type="text/javascript" src="/sdk/js/canvas-all.js></script>
ホストされた SDK を参照する場合の include ステートメントの例は次のとおりです。
<script type="text/javascript"
src="https://<instance>.salesforce.com/canvas/sdk/js/33.0/canvas-all.js"></script>
Salesforce サーバにある SDK を参照する機能は、Web アプリケーションにある SDK ファ
イル、あるいは Visualforce ページを含める場合に便利です。
ユーザインターフェースの考慮事項
キャンバスアプリケーションのユーザインターフェースを設計および実装するときに
は、次のような点に留意します。
キャンバスのサイズ
キャンバスアプリケーションのフレームサイズはアプリケーションが表示されて
いる場所によって異なります。SDK を使用する場合、これらの値は Dimensions キャ
ンバスオブジェクトで返されます。
241
第 15 章 Force.com Canvas
ロゴ画像
キャンバスアプリケーションに関連付けられたロゴ画像は、ユーザがそのキャン
バスアプリケーションをインストールするときか、OAuth 認証中にアプリケーショ
ンの実行を許可するように要求されるときに表示されます。256 ピクセル (高さ) ×
256 ピクセル (幅) のサイズの画像を使用することをお勧めします。
アイコン画像
キャンバスアプリケーションに関連付けられたアイコン画像は、次の場所に表示
されます。
• Chatter タブの Chatter アプリケーションリストにある、自分のキャンバスアプリ
ケーションへのリンクの左側。
• キャンバスアプリケーションのプレビューアにある、自分のキャンバスアプリ
ケーションへのリンクの左側。
サムネイル画像
キャンバスアプリケーションのフィード項目に関連付けられたサムネイル画像は、
フィードのキャンバスアプリケーションにアクセスすると表示されます。指定さ
れている場合は、この画像はフィード項目のタイトルと説明の横に表示されます。
120 ピクセル (高さ) × 120 ピクセル (幅) 以下のサイズの画像を使用することをお勧め
します。
Visualforce と Force.com Canvas を併用する場合の考慮
事項
<apex:canvasApp> コンポーネントを使用するときの考慮事項は、次のとおりです。
• <apex:canvasApp> コンポーネントは、Force.com Canvas が有効になっている組織
で、バージョン 27.0 以降の Visualforce ページでのみ使用できます。
• オブジェクトの詳細レイアウトにキャンバスアプリケーションを含める場合、ペー
ジレイアウトと <apex:canvasApp> コンポーネントにキャンバスアプリケーショ
ンの高さを指定する必要があります。
• 場所 — キャンバスアプリケーションが Visualforce ページにある場合、
Environment.displayLocation 項目には Visualforce という値が含まれま
す。
242
第 15 章 Force.com Canvas
Force.com Canvas の制限
Force.com Canvas はマルチテナント環境で実行されるため、共有リソースが確実に保護
されるように制限が課せられます。
説明
制限
Chatter タブに表示できるユーザあたりの 50
キャンバスアプリケーション数。最初の
50 個のキャンバスアプリケーションのみ
が表示されます (アルファベット順)。
ユーザあたりの、1 日 (24 時間) あたりの
Force.com Canvas コール数
5,000
ユーザあたりの、1 日あたりの Heroku ク
イックスタートコール
100
これには、コンテキストを取得するため
の SDK コールと、署名付き要求コールが
含まれます。SignedRequest メソッドをコー
ルすると、実際には、そのメソッド用の
コールと内部ロギング用のコールという
2 つのコールが行われます。
Heroku アカウントには、実行できるコー
ル数に独自の制限があります。
クロスドメイン XHR
キャンバスアプリケーションは、iFrame の Salesforce ページにロードされます。このた
め、キャンバスアプリケーションは (それ自体のドメインでは) XHR (XML HTTP 要求) の
コールを *.salesforce.com ドメインに返すことはできません。独自のプロキシを SDK の一
部として作成およびリリースできますが、Force.com Canvas には、JavaScript で作成され
たクライアント側のプロキシが用意されています。このプロキシを使用して、クライ
アント側の XHR コールを Salesforce に返すことができます。
クライアントからこのプロキシを使用して XHR 要求を作成すると、API によってその
要求が外部の iFrame に転送され、要求が自動的に送信されます。要求が完了すると、
SDK はその結果を使用してクライアントのコールバック関数をコールします。
243
第 15 章 Force.com Canvas
メモ: SDK ではクロスドメイン XHR コールがサポートされていますが、同じドメ
インコールの作成には使用しないでください。
リソース
Force.com Canvas に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• Force.com Canvas 開発者ガイド
• API およびインテグレーションフォーラム (「Canvas」とタグ付けされた投稿を参照)
244
第 16 章
Tooling API
Tooling API を使用すると、Salesforce アプリケーション用のカスタム開発ツールを作成で
きます。
Tooling API を使用するケース
Tooling API は、Force.com アプリケーション用のカスタム開発ツールを作成可能な SOAP
および REST インターフェースを提供します。Tooling API は、開発者ツール作成で使用
され、REST や SOAP からアクセスできるオブジェクトを公開します。また、Salesforce
REST API や SOAP API と同様に機能します。
たとえば、Tooling API を使用して次のことができます。
• 既存の Force.com ツールに機能を追加する。
• Force.com 開発用の動的モジュールをエンタープライズインテグレーションツール
に組み込む。
• 特定のアプリケーションまたはサービス専用の開発ツールを作成する。
こうした目標を達成するために、Tooling API には、次の処理を実行するためのコール
が用意されています。
• Apex クラスおよびトリガと Visualforce ページおよびコンポーネントの作業コピーを
管理する。
• 静的リソースファイルの作業コピーを管理する。
• Apex クラスおよびトリガと Visualforce ページおよびコンポーネントの作業コピーに
更新やエラーがないかチェックし、変更を組織にコミットする。
• ヒープダンプマーカーを設定する。
• Apex 実行時に Apex コードまたは SOQL ステートメントをフロート表示する。
• Apex を匿名実行する。
• チェックポイントを設定して自分または他のユーザ用にログファイルを生成する。
• デバッグログおよびヒープダンプファイルにアクセスする。
• カスタムオブジェクトのカスタム項目を管理する。
245
第 16 章 Tooling API
• コードカバー率の結果にアクセスする。
次の Java コードスニペットでは、Tooling API の SOAP ベースのインターフェースを使用
して、SayHello というメソッドが 1 つ含まれる Apex クラスをプログラムで作成しま
す。
String classBody = "public class Messages {\n"
+ "public string SayHello() {\n"
+ " return 'Hello';\n" + "}\n"
+ "}";
// create a new ApexClass object and set the body
ApexClass apexClass = new ApexClass();
apexClass.Body = classBody;
ApexClass[] classes = { apexClass };
// call create() to add the class
SaveResult[] saveResults = sforce.create(classes);
for (int i = 0; i < saveResults.Length; i++)
{
if (saveResults[i].success)
{
Console.WriteLine("Successfully created Class: " +
saveResults[i].id);
}
246
第 16 章 Tooling API
else
{
Console.WriteLine("Error: could not create Class ");
Console.WriteLine("
The error reported was: " +
saveResults[i].errors[0].message + "\n");
}
}
サポート対象のエディションとプラットフォーム
Tooling API を使用するには、組織で Enterprise Edition、Performance Edition、Unlimited Edition、
または Developer Edition を使用している必要があります。既存の Salesforce のお客様が
Enterprise Edition、Unlimited Edition、または Performance Edition にアップグレードする場合
は、担当者にご連絡ください。
リソース
Tooling API に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• Tooling API Developer's Guide
• API とインテグレーションに関するフォーラム
247
第 17 章
Salesforce1 レポート REST API
REST ベースの Salesforce1 レポート API では、Salesforce のレポートデータにプログラムを
使用してアクセスできます。
Salesforce1 レポート REST API を使用するケース
Salesforce1 レポート REST API では、レポートビルダーで定義されたレポートデータを
Salesforce プラットフォーム内外で任意の Web アプリケーションまたはモバイルアプリ
ケーションに統合できます。たとえば、API を使用して、各四半期の最優秀担当者の
スナップ写真を掲載した Chatter 投稿をトリガできます。
Salesforce1 レポート API を使用すると、次のことができます。
• レポートデータをカスタムオブジェクトに統合する。
• API の上位にリッチな視覚効果を定義して、データのアニメーションを実行する。
• カスタムダッシュボードを作成する。
• レポートタスクを自動化する。
API リソースでは、概要レベルでレポートデータのクエリおよび絞り込みができます。
次の操作を実行できます。
• 表形式レポート、サマリーレポート、またはマトリックスレポートを同期または
非同期に実行する。
• 特定のデータをその場で絞り込む。
• レポートメタデータをクエリする。
たとえば、Salesforce1 レポート API の Execute Async REST リソースを使用して、非同期に
レポートを実行できます。その場合、次の形式の REST リソース URL を使用します。
/services/data/<latest API version>/analytics/reports/<report
ID>/instances
249
第 17 章 Salesforce1 レポート REST API
POST 要求では、必要なグルーピングと検索条件を示す JSON データを指定します。要
求が成功すると、Salesforce はレポートを実行キューに入れ、レポートの状況と結果を
取得する場所に関する情報が含まれる、次のような JSON 応答データを返します。
{
"id": "0LGD000000000IjOAI",
"requestDate": "2013-08-12T18:39:06Z",
"status": "New",
"ownerId": "005D0000001KvxRIAS",
"url":
"/services/data/v29.0/analytics/reports/00OD0000001ZbP7MAK/instances/0LGD000000000IjOAI",
"hasDetailRows": false,
"completionDate": null
}
サポート対象のエディションとプラットフォーム
Salesforce1 レポート API を使用するには、組織で Enterprise Edition、Performance Edition、
Unlimited Edition、または Developer Edition を使用する必要があります。既存の Salesforce
のお客様が Enterprise Edition、Unlimited Edition、または Performance Edition にアップグレー
ドする場合は、担当者にご連絡ください。
ベストプラクティス
このセクションで説明するベストプラクティスを考慮してください。
250
第 17 章 Salesforce1 レポート REST API
要求データおよび応答データには JSON を使用する
Salesforce1 レポート REST API では、JSON の要求データおよび応答データはサポートされ
ますが、XML はサポートされません。リクエストボディで Salesforce1 レポート API を使
用する場合、要求ヘッダーで Content-Type: application/json を使用します。
Salesforce1 レポート API の制限
Salesforce1 レポート API には次の制限があります。
レポート API の制限
• クロス条件、標準レポート条件、行制限による絞り込みは、データを絞り込む
場合には使用できません。
• 履歴トレンドレポートは、マトリックスレポートでのみサポートされていま
す。
• API では、列として選択された 100 個までの項目を含むレポートのみ処理できま
す。
• 最近参照した 200 個までのレポートのリストが返されます。
• 1 時間あたり 500 回までのレポートの同期実行を組織で要求できます。
• API では、一度に 20 回までのレポートの同期実行の要求をサポートしています。
• 非同期に実行された 2,000 個までのレポートインスタンスのリストが返されま
す。
• API では、レポートの非同期実行の結果を取得するために、一度に 200 件までの
要求をサポートしています。
• 1 時間あたり 1,200 回までの非同期要求を組織で要求できます。
• レポートの非同期実行の結果は、24 時間以内に使用できます。
• API では、レポートの最初の 2,000 行までが返されます。検索条件を使用して結
果を絞り込むことができます。
• レポートの実行時にカスタム項目の検索条件を 20 件まで追加できます。
ダッシュボード API の制限
• 1 時間あたり 200 回までのダッシュボードの更新を組織で要求できます。
• 1 時間あたり最大 5,000 個のダッシュボードの結果を組織で要求できます。
251
第 17 章 Salesforce1 レポート REST API
リソース
Salesforce1 レポート REST API に関する次のリソースについては、Salesforce 開発者のネッ
トワーク (http://developer.salesforce.com/docs) を検索してください。
• Salesforce1 レポート REST API 開発者ガイド
• API とインテグレーションに関するフォーラム
252
コラボレーション
第 18 章
Chatter REST API
Chatter REST API を使用すると、プログラムを介して Salesforce 組織の Chatter フィード、
グループ、およびソーシャルデータにアクセスできます。
Chatter REST API を使用するケース
Chatter REST API は、Chatter フィードと、ユーザ、グループ、フォロワー、ファイルなど
のソーシャルデータへのプログラムを使用したアクセスを提供します。Chatter REST API
を使用して、モバイルアプリケーション、イントラネットサイト、およびサードパー
ティ Web アプリケーションなど、さまざまなアプリケーションに Chatter を統合しま
す。Chatter REST API は、Facebook や Twitter などのフィードを提供する他の企業から公開
されている API に類似しています。
次の場合は、Chatter REST API を使用してください。
• Chatter フィードを表示するモバイルクライアントを作成する。
• サードパーティ製 Web アプリケーションを Chatter と統合して、ユーザのグループ
に行動について通知する。
• ユーザが認証された後、Chatter フィードをイントラネットサイトなどの外部シス
テムに表示する。
• フィードをサードパーティサイトに統合して利用可能にする。たとえば、投稿に
#tweet ハッシュタグが含まれる場合は常に Chatter 項目を Twitter に投稿するアプリ
ケーションなどがあります。
• Chatter と連動し、フィード上で通知を行える簡単なゲームを作成する。たとえば、
インセンティブが支給されるセールスコンテストなどが考えられます。
• 組織のブランド情報を含むカスタムの Chatter 用スキンを作成する。
Chatter REST API は、Chatter データを操作しやすくすることで SOAP API および REST API を
補足します。ConnectApi 名前空間の Apex クラスでは多くの Chatter REST API リソース
アクションも静的メソッドとして公開されています。この名前空間は、Chatter in Apex
とも呼ばれます。Chatter in Apexは、Apexからの HTTP コールアウトを使用せずにForce.com
プラットフォームで Chatter アプリケーションを開発するために使用します。
253
第 18 章 Chatter REST API
サポート対象のエディションとプラットフォーム
Chatter REST API は、Personal Edition を除くすべてのエディションで使用できます。また、
ほとんどの機能では、組織で Chatter が有効になっている必要があります。
Chatter REST API クイックスタート
Salesforce に接続して認証し、Chatter REST API に対して要求を実行して応答を確認しま
す。
前提条件
クイックスタートを開始する前に、次の前提条件を満たしていることを確認してくだ
さい。
次のことに習熟しておいてください。
• cURL。コマンドラインツールであり、クイックスタートでは Salesforce への HTTP 要
求を行うクライアントアプリケーションとして使用します。cURL は、多くの Linux
システムや Mac システムにあらかじめインストールされています。Windows バー
ジョンは、curl.haxx.se/ からダウンロードできます。Windows で HTTPS を使用
する場合、システムが SSL 対応の cURL の要件を満たしていることを確認してくだ
さい。
メモ: cURL はオープンソースのツールで、Salesforce ではサポートされていませ
ん。
• JavaScript Object Notation (JSON)。このクイックスタートで返されるデータ形式です。
• OAuth 2.0。Salesforce が認証に使用するフレームワークです。このクイックスタート
では手順を説明しますが、OAuth の用語と概念に習熟しておくと役立ちます。
ステップ 1: Salesforce Developer Edition 組織を取得する
まだ Force.com 開発者コミュニティのメンバーでない場合、
developer.salesforce.com/signup にアクセスし、Developer Edition 組織のサイン
アップの説明に従ってください。すでに Enterprise Edition、Unlimited Edition、または
254
第 18 章 Chatter REST API
Performance Edition を所有している場合でも、組織の使用中のデータを保護するために、
サンプルデータに対するソリューションの開発、ステージングおよびテストには
Developer Edition を使用します。これは、特に、(データをただ参照するだけのアプリ
ケーションに対し) データを挿入、更新または削除するアプリケーションの場合に該
当します。
Developer Edition 組織をすでに所有している場合は、「API の有効化」権限があることを
確認します。この権限はデフォルトで有効になっていますが、管理者によって変更さ
れている場合があります。詳細は、Salesforce ユーザインターフェースのヘルプを参照
してください。
ステップ 2: 認証を設定する
Salesforce 組織で接続アプリケーションを作成し、OAuth を有効にします。クライアン
トアプリケーションは、接続アプリケーションを使用して Salesforce に接続します。
1. Developer Edition 組織で、[設定] から [作成] > [アプリケーション] をクリックし、
[接続アプリケーション] セクションで [新規] をクリックして新しい接続アプリ
ケーションを作成します。
クライアントは、接続アプリケーションが組織で定義されていなくても、接続
アプリケーションを使用して組織にサインインできます。
2. 接続アプリケーション名を入力します。
3. 取引先責任者のメールと、必要に応じてその他の情報を入力します。
4. [OAuth 設定の有効化] を選択します。
5. [コールバック URL] を入力します。これはセキュアである必要があります。
http:// は機能せず、https:// のみが機能します。
このクイックスタートでは、「https://」と入力してください。
6. OAuth の範囲を入力します。接続アプリケーションでアクセスを許可する他の
範囲に加え、[Chatter フィードへのアクセスと管理] を選択します。
7. [保存] をクリックします。
[コンシューマ鍵] が作成され、表示されます。また、[コンシューマの秘密] が
作成されます (表示するにはリンクをクリックします)。
255
第 18 章 Chatter REST API
ステップ 3: OAuth を使用して Chatter REST API に接続
する
OAuth を使用して Salesforce に接続し、アクセストークンを取得します。アクセストー
クンを要求で Chatter REST API に渡します。
「ステップ 2: 認証を設定する」を完了し、接続アプリケーションを作成してからこの
タスクを開始します。
作成した接続アプリケーションで使用される用語と、例で使用される OAuth のプロパ
ティの対応付けを次の表に示します。OAuth 2.0 仕様では、「コンシューマ」ではなく
「クライアント」という用語を使用します。
接続アプリケーションのアプリケーショ 例の値
ンラベル
コンシューマ鍵
client_id
コンシューマの秘密
client_secret
メモ: このクイックスタートでは、ユーザ名パスワード OAuth 認証フローを使用
します。ユーザ名パスワード認証フローでは、ユーザのログイン情報をやりとり
する必要があります。この認証フローは、このクイックスタートのように必要な
場合にのみ使用してください。更新トークンは発行されません。さらに、Salesforce
Communitiesではユーザ名パスワード認証フローはサポートされていません。この
クイックスタートでは、コミュニティ URL への要求は行わないでください。
Salesforce への要求を行うには、次の例に組織の値を代入します。
1. アクセストークンを生成します。
次の cURL コマンドはアクセストークンを生成します。
curl --form client_id=3MVG9PhR6g6B7ps4xDycwGrI4PvjVZvK9
--form client_secret=8870355475032095511
--form grant_type=password
--form [email protected]
256
第 18 章 Chatter REST API
--form password=1Lsfdc!
https://login.salesforce.com/services/oauth2/token
ヒント: 複数行コマンドを Mac または Linux コマンドラインインターフェー
スに貼り付ける場合、各行をバックスラッシュ (「\」) でエスケープして
コマンドが次の行に続くことを示します。エスケープされた行は次のよ
うになります。
curl --form client_id=3MVG9PhR6g6B7ps4xDycwGrI4PvjVZvK9 \
複数行コマンドを Windows コマンドプロンプトに貼り付ける場合、各行
をキャレット (「^」) でエスケープします。エスケープされた行は次のよ
うになります。
curl --form client_id=3MVG9PhR6g6B7ps4xDycwGrI4PvjVZvK9 ^
応答には、次のようにサーバインスタンスとアクセストークンが含まれます。
{
"id":"https://login.salesforce.com/id/00Di0000000hT9uEAE/005i00000022uIbAAI",
"issued_at":"1302907727777",
"instance_url":"https://na1.salesforce.com",
"signature":"5jcevY5fUai0lWntuSxkwBzWcvRjd01RCOkIBZpyGv0=",
"access_token":"00DD0000000FJ6T!AQkAQPde_DMF2vGzddfZmBRS95GojDbtA
rKkgukAgZP0OVFYY5KkAqhLw9ejeKIlpJ3FgwGAWeRlBiWRt8mfXEuAZGbZNosk"
}
257
第 18 章 Chatter REST API
2. Chatter REST API リソースを要求するには、返された instance_url をサーバイ
ンスタンスとして使用します。返された access_token を Authorization
要求ヘッダーで Bearer トークンとして渡します。
curl -X GET
https://na1.salesforce.com/services/data/v33.0/chatter/users/me
-H 'Authorization: Bearer
00DD0000000FJ6T!AQkAQPde_DMF2vGzddfZmBRS95Goj
DbtArKkgukAgZP0OVFYY5KkAqhLw9ejeKIlpJ3FgwGAWeRlBiWRt8mfXEuAZGbZNosk'
この例では次の値を使用しています。
プロパティ
値
サーバインスタンス
na1.salesforce.com
client_id
3MVG9PhR6g6B7ps4xDycwGrI4PvjVZvK9
client_secret
8870355475032095511
grant_type
password
grant_type の値は使用する OAuth 認証
フローに応じて異なります。
username
[email protected]
password
1Lsfdc!
Salesforce Communities への接続
OAuth を使用して Salesforce のコミュニティに接続するには、サーバインスタンス名を
コミュニティ URL へのフルパスで置き換えます。
Salesforceコミュニティに接続するには、OAuth Web サーバおよびユーザエージェント
ワークフローを使用します。
258
第 18 章 Chatter REST API
承認 URL を使用してユーザを認証するには、login.salesforce.com ホスト名をコ
ミュニティ URL へのフルパスで置き換えます。次の例は コミュニティ URL ではありま
せん。
https://login.salesforce.com/services/oauth2/authorize?
response_type=token&client_id=your_app_id&redirect_uri=your_redirect_uris
コミュニティ URL は、次のようになります。
https://acme.force.com/customers/services/oauth2/authorize?
response_type=token&client_id=your_app_id&redirect_uri=your_redirect_uri
正常に実装されると、この URL によりユーザはアプリケーションのブランド名が入っ
たログインページに移動します。アプリケーションを認証したら、ユーザアクセス
トークンを設定し、将来の認証に備えてトークンを更新します。トークンエンドポイ
ントの要求で、次のようにホストをコミュニティで置き換えます。
https://acme.force.com/customers/services/oauth2/token
Chatter REST API リソースを要求するには、Salesforce ホスト名を使用してコミュニティ ID
を次のように指定します。
https://na1.salesforce.com/services/data/v29.0/connect
/communities/communityId/chatter/feeds/news/me/feed-elements
または、ホスト名をコミュニティ URL へのフルパスで置き換えます。
https://communitydomain.force.com/communitypath/services/data/v29.0/connect
/communities/communityId/chatter/feeds/news/me/feed-elements
ベストプラクティス
このセクションのベストプラクティスを考慮してください。
259
第 18 章 Chatter REST API
Chatter REST API の制限
Chatter REST API 要求はレート制限の対象になります。Chatter REST API には、ユーザ、ア
プリケーション、および時間ごとのレート制限があります。レート制限を超過する
と、すべての Chatter REST API リソースが 503 Service Unavailable エラーコードを返します。
ワイルドカードを使用したテキストパターンの照合
Chatter REST API と Chatter in Apex の検索でテキストパターンを一致させるには、ワイルド
カード文字を使用します。ワイルドカードが一般的に使用されるのはフィードを検索
するときです。q パラメータで検索文字列とワイルドカードを渡します。次の例は、
Chatter REST API 要求です。
/chatter/feed-items?q=chat*
次の例は、Chatter in Apex メソッドコールです。
ConnectApi.ChatterFeeds.searchFeedItems(null, 'chat*');
レスポンスボディの符号化について
Chatter REST APIは、ユーザが送信したコンテンツを配信します。このコンテンツの多く
は、入力時に絞り込みされず、サードパーティのモバイルアプリケーションや Web ア
プリケーションなど、雑多なソースから送られてくる場合があります。そのため、
Chatter REST API出力を使用するアプリケーションを作成する開発者は、データを使用す
るコンテキスト用に出力を適切に処理するように考慮する必要があります。
Chatter REST API 文字列は、デフォルトでは最小限に符号化された HTML エンティティで
あり、多くの場合は HTML タグ間の表示に適していますが、他の HTML コンテキストに
は適しているとは限りません。Chatter REST API出力は、多くのコンテキストで使用され
る可能性があります。開発者は、デフォルトのエンティティ符号化がすべてのコンテ
キストに適していると想定しないでください。特に、Chatter REST API 出力を HTML 属性
値内、URL 内、JavasScript 内、スクリプトタグ内、CSS 内で使用する場合は、それぞれ
異なる符号化とホワイトリスト登録が必要になります。
ネイティブのモバイルアプリケーションなど、非 HTML コンテキストの場合、Chatter
REST API クライアントが、要求内の X-Chatter-Entity-Encoding HTTP ヘッダーを
false に設定して、未加工 (符号化されていない) の出力を要求する場合があります。
260
第 18 章 Chatter REST API
Chatter REST API は、応答ペイロードに含まれる URL 値に特殊な符号化を行います。URL
の主部分は、RFC2396 に従って URL 符号化され、クエリ文字列は HTML 形式で符号化さ
れます。この符号化は無効にできません。
リソース
Chatter REST API に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• Chatter REST API 開発者ガイド
• Chatter コードレシピ
• Chatter REST API 早見表
• Chatter 開発フォーラム
261
モバイル
第 19 章
Salesforce Mobile SDK
Salesforce Mobile SDK は、Salesforce と統合された高度なモバイルアプリケーションを容易
に作成するためのフレームワークとツールのセットを提供します。
Mobile SDK を使用するケース
Salesforce Mobile SDK を使用して、iOS 用のネイティブ Objective-C アプリケーションと
Android 用の Java アプリケーションを開発できます。また、HTML5 と JavaScript で記述さ
れたハイブリッドアプリケーション用のネイティブコンテナを提供することもできま
す。iOS および Android 用の npm スクリプトは、ネイティブアプリケーションやハイブ
リッドアプリケーションの開発を始めるときに役立ちます。Salesforce Mobile SDK には、
次の機能があります。
• ネイティブのデバイスサービス。幅広い iOS および Android デバイスのカメラ、GPS、
連絡先などのデバイス機能にアクセスできます。
• セキュアなオフラインストレージとデータ同期。ネットワーク接続が限定されて
いるか、ネットワーク接続がない場合でも、継続して機能するアプリケーション
を作成できます。デバイスに保存されたデータは、セキュアに暗号化され、デバ
イスの紛失や盗難時も安全です。
• アプリケーションのセキュリティ。モバイルアプリケーションでログインページ
や汎用的な認証を再作成する必要がありません。Mobile SDK では、アプリケーショ
ンをエンタープライズセキュリティ管理とすばやく容易に統合できます。
Mobile SDK はまた、以下の機能を提供することで Force.com クラウドアーキテクチャと
統合します。
• JavaScript を介して Salesforce データにアクセスする SmartSync Data Framework
• 高度なデータクエリをサポートする SmartSQL
• ネイティブアプリケーションおよびハイブリッドアプリケーションのデータ同期
• すぐに使える Force.com 接続アプリケーションポリシーの実装
• 永続化機能や更新機能を含む、OAuth ログイン情報管理
• Salesforce Communities ログインと外部認証プロバイダのサポート
263
第 19 章 Salesforce Mobile SDK
• 転送通知のための Salesforce を使用した組み込み登録
• Salesforce REST API のラッパー
• ネイティブ iOS および Android アプリケーションを作成するためのライブラリ
• ハイブリッドアプリケーション作成用の Cordova ベースのコンテナ
サポート対象のエディションとプラットフォーム
Mobile SDK を使用するには、以下の条件を満たす必要があります。
• iOS アプリケーション (ハイブリッドまたはネイティブ) を作成するには、Mac OS X
10.8 (「Mountain Lion」) 以降、iOS 7 以降、Xcode 5.0 以降が必要です。
• Android アプリケーション (ハイブリッドまたはネイティブ) を作成するには、Java
JDK 6、Eclipse、Apache Ant、Eclipse 用の Android ADT プラグイン、および Android SDK
Tools バージョン 21 以降が必要です。
• Mobile SDK リソースは、ソーシャルコーディングコミュニティである GitHub に存在
します。すべてのファイルには公開リポジトリででもアクセスできますが、コミュ
ニティに参加することをお勧めします。https://github.com/forcedotcom
Salesforce との統合に Mobile SDK をどう使用するかに応じて、Visualforce、Apex、または
REST API の使用も必要になることがあります。これらの API について、サポート対象の
Salesforce エディションや必要な追加要件の詳細は、このガイドの該当するセクション
を参照してください。
264
第 20 章
リソース
Salesforce Mobile SDK に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• Salesforce Mobile SDK 開発ガイド
• Platform Mobile Services サイト
• Mobile SDK リリースノート
• モバイル開発フォーラム
265
Marketing Cloud
第 21 章
ExactTarget API
ExactTarget のコアサービスには、Fuel という受賞歴を誇る製品があります。Fuel は、数
多くの世界トップブランドにマルチチャネルマーケティングプログラムを提供しま
す。ExactTarget Marketing Cloud の基盤である Fuel は、サードパーティ開発のためにオー
プンとなっています。ExactTarget の業界最高レベルのデジタルマーケティング製品を
ベースとした構築、拡張、統合が可能です。
このガイドの読者である開発者は、ExactTarget 顧客またはパートナー向けの開発を行
うにあたり、どのように開始すればよいか模索していることと思います。次の各セク
ションでは、Fuel について説明し、ExactTarget Marketing Cloud を活用して革新的な顧客
タッチポイントを構築する方法を紹介します。
Fuel を使用したメール送信
Fuel の一般的な用途の 1 つは、メールの送信です。このセクションでは、登録者リス
トにメールを送信するプロセスを段階的に説明します。記載の例は、Fuel をプログラ
267
第 21 章 ExactTarget API
ミングして、プロモーション用およびトランザクション用のメールを送信するために
必要なさまざまな基本概念を説明することを目的としています。
特に、購入活動に関連付けられた属性を登録者データモデルに追加する方法を示しま
す。また、リストの作成、そのリストへの登録者の追加、メールの作成、リストへの
メールの送信、送信からの追跡イベントの取得などをすべてプログラミングによって
実行する方法も解説します。最後に、コンテンツスクリプト機能により、追加のデー
タセットを使用して高度にパーソナライズされたメッセージを作成する方法を示しま
す。
基本的な概念: 登録者、属性、リスト、メール
コードを記述する前に、ExactTarget Marketing Cloud の主な概念である登録者、リスト、
プロファイル属性、メールについて説明します。これらの 4 つの概念は、取引先責任
者、登録、コンテンツを結び付けるメールコミュニケーションの基本です。
登録者とは、メールアドレスがあり、いずれかの状況に該当する取引先責任者です。
登録者の状況には有効、登録解除、保留があります。登録者が有効の場合は、Marketing
Cloud からそのメールアドレスにメールを送信できます。登録者が登録解除されてい
る場合は、そのメールアドレスに Marketing Cloud からメールが送信されません。登録
者が保留の場合は、そのメールアドレスへの以前のメール送信の試行が不達になって
います。
268
第 21 章 ExactTarget API
リストには複数の登録者が含まれます。リストを利用すると複数の登録者に最も簡単
にメールを送信できます。Marketing Cloud の各取引先に「すべての登録者」リストがあ
り、その名が示すとおり、すべてのリストのすべての登録者が掲載されています。取
引先のリストはどれも「すべての登録者」リストの子とみなされるため、登録者が
「すべての登録者」リストで登録解除になると、すべてのリストで登録解除とみなさ
れ、Marketing Cloud からその登録者にメールを送信できなくなります。
プロファイル属性は、任意の名前と値のペアで、各登録者に関連付けることができま
す。たとえば、プロファイル属性を使用して登録者の名前を保存すれば、その登録者
へのメールをパーソナライズして登録者の名前 (「デイル様」など) をメール本文で使
用できます。プロファイル属性は、「すべての登録者」リストのレベルで設定され、
作成されたすべての子リストに適用されます。取引先には最大 200 種のプロファイル
属性を作成できます。データ拡張により、さらに柔軟性の高い属性モデルも存在しま
す。メッセージのパーソナライズについての詳細は、このガイドのセクション「デー
タ拡張 (ページ 292)」を参照してください。
メールは登録者のリストに配信されます。各メールは、プロファイル属性で表される
置換文字列を使用してパーソナライズできるテンプレートです。メールテンプレート
は、スケルトン構造の 1 つのメールが本番データソースを使用して自動的に送信でき
る完成形メールになるまでを管理します。この章のこのチュートリアルでは、Fuel SDK
を使用してメールを作成します。
このチュートリアルでは、Fuel を使用して、プログラムによるプロファイル属性の作
成、リストの作成、そのリストへの登録者の追加、パーソナライズされたメールの作
成、リストへのメールの送信、開封やクリックなどの追跡イベントの取得を行う方法
を学びます。このチュートリアルの最後のセクションで、データ拡張や AMPscript など
の高度な Marketing Cloud 機能を使用してメールをさらにパーソナライズする方法を学
びます。
開発環境の設定
コードを記述する前に、開発環境を設定する必要があります。では始めましょう。
269
第 21 章 ExactTarget API
Fuel SDK
Fuel SDK
まず、お使いの環境向けの Fuel SDK をダウンロードします。Fuel SDK は、Fuel の API の
ラッパーであり、開発者はネイティブ言語の構成要素を使用してこれらの API に統合
できます。Fuel SDK は、https://code.exacttarget.com/sdks で入手できます。Fuel SDK は、
Java、.NET、PHP、Python、Ruby 向けに提供されています。salesforce.com ではアプリケー
ションの構築に PHP SDK を使用しますが、どの Fuel SDK も共通するパターンを採用して
いるため、サンプルコードを他の SDK にかなり簡単に適用できます。PHP SDK を、ワー
クスペースの sdk というサブディレクトリにインストールします。SDK の README に
記載されているとおりにすべての連動関係がインストールされいてることを確認しま
す。アプリケーションの作成 (ページ 276)に SDK の設定方法が説明されていますが、こ
こでは参照しません。
SDK は、Fuel の SOAP にも REST API にも対応するプロトコル非依存のインターフェース
のほか、自動トークン管理など開発時間の短縮を目的とするその他の機能も備えてい
ます。salesforce.com の SOAP API は、最も古く最も包括的な API ですが、その機能は
ExactTarget のメールアプリケーションに限定され、すべての SOAP API と同様に、動作が
かなり重くなります。salesforce.com の REST API は比較的新しく、SOAP API ほど包括的で
はありませんが、Marketing Cloud の幅広い機能を公開し、軽く、使いやすくなっていま
す (リリースごとにより包括的になっています)。SOAP API と REST API は OAuth 2 に基づ
く 1 つの一般的な認証メカニズムを共有しています。
SDK を使用すれば、双方の長所を活用できます。さらに、ほとんどの場合、SDK を使
用すれば同じタスクを少ないコードで実行できます。また、salesforce.com では、一般
的なパターンとベストプラクティスを直接 SDK にカプセル化しています。そのため、
Fuel プラットフォームとの統合には、SDK を使用するのが最も一般的な方法です。
各自の環境向けの SDK がない場合や SDK を使用しない場合も心配はいりません。API に
はいつでも直接アクセスできます。このアクセス方法については数例を示しますが、
すべてを説明することはできません。API の使用方法については、Code@ExactTarget で
詳しい情報を直接確認できます。
270
第 21 章 ExactTarget API
App Center
次に、App Center アカウントを作成して、そのアカウントにログインします。App Center
は、Fuel API を使用したり、ExactTarget Marketing Cloud アプリケーションを構築したりす
るための中央開発コンソールです。アカウントを作成する手順は、次のとおりです。
1. https://code.exacttarget.com/ に移動します。
2. [App Center (アプリケーションセンター)] をクリックします。
3. [Create an account now (今すぐアカウントを作成)] をクリックします。
4. フォームに入力してから [Create new account (アカウントを新規作成)] をクリッ
クします。
5. 受信した確認メールの [Update Profile (プロファイルを更新)] をクリックして、
パスワードを設定します。
Code@ExactTarget でアカウントを作成し、そのアカウントにログインして適切な Fuel SDK
(該当する場合) をダウンロードしたら、App Center を使用してアプリケーションを
ExactTarget に接続します。App Center は、アプリケーションの構築や Fuel プラットフォー
ムとの統合に使用する中央開発コンソールです。Code@ExactTarget 開発者コミュニティ
の拡張機能である App Center を使用すれば、ExactTarget 開発者は API キーを取得して Fuel
API で認証したり、Marketing Cloud アプリケーションを作成および管理したりできます。
App Center は Code@ExactTarget の上部にあるメニューバーからアクセスできます。
1. https://appcenter.exacttarget.com/ に移動します。
2. 右上の [ログイン] リンクをクリックすると、次の画面に移動します。
3. ログイン情報を入力してから、[ログイン] をクリックします。
4. ログインすると、メインナビゲーションバーに [App Center (アプリケーション
センター)] ボタンが表示されます。そのボタンをクリックして、登録プロセス
に進みます。フォームに入力したら [次へ] をクリックします。
5. エンドユーザ使用許諾契約に同意して続行します。
EULA に同意したあと、最初のアプリケーションを作成できます。
App Center の各アプリケーションは、Fuel プラットフォームに接続されているアプリ
ケーションを表します。Force.com の接続アプリケーションに慣れているユーザであれ
ば、Fuel の接続アプリケーションの概念もすぐに理解できます。現在、3 つの種別の
接続アプリケーションがあります。
271
第 21 章 ExactTarget API
• Server-to-Server アプリケーションは、セキュアな API ベースのサーバ間インテグ
レーションです。Fuel の API を使用して、作業を自動化したり、ビジネスシステム
を統合したりする場合は Server-to-Server アプリケーションを作成します。Server-to-Server
アプリケーションは、OAuth 2.0 クライアントのログイン情報フローを使用して、
Fuel の認証サービスから直接アクセストークンを取得します。
• Marketing Cloud アプリケーションは、ExactTarget Marketing Cloud 内に存在し、Marketing
Cloud のアプリケーションメニューから起動されます。Marketing Cloud アプリケー
ションには、組織で作成されるカスタムアプリケーションや、ExactTarget HubExchange
からインストールされるアプリケーションがあります。Marketing Cloud アプリケー
ションは、JSON Web トークン (JWT) を使用して、ログインユーザの代わりにアクセ
ストークンを取得します。
• MobilePush アプリケーションは、MobilePush を使用して転送メッセージ経由でユー
ザと通信する iOS、Android、または Blackberry モバイルプラットフォーム用に構築さ
れたアプリケーションです。MobilePush アプリケーションは、コンシューマグレー
ドアプリケーションとして分類され、有効期間の長い限定的なアクセストークン
を使用します。
アプリケーションを接続する
ここでは ExactTarget Marketing Cloud との API ベースのインテグレーションを構築するた
め、Server-to-Server アプリケーションを作成します。App Center を表示したら、
[Server-to-Server (サーバからサーバ)] をクリックします。アプリケーションの名前と説
272
第 21 章 ExactTarget API
明を入力し、パッケージ名に myapp と指定します。パッケージは、ExactTarget Fuel の
アプリケーションを一意に識別します。
アプリケーションをアカウントに接続する
次に、アプリケーションを ExactTarget Marketing Cloud アカウントにリンクする必要があ
ります。これは、API コールを実行するときにアプリケーションがアクセスするアカ
ウントで、アプリケーションの開発環境と考えることができます。
初めてアプリケーションをアカウントにリンクする場合、ドロップダウンメニューか
ら [新規] を選択する必要があります。App Center ではアカウントの参照が保存される
ため、今後のアプリケーションで同じアカウントを使用する場合、新しいアカウント
をリンクする代わりにドロップダウンメニューからそのアカウントを選択できます。
アカウントをリンクしたら、App Center にアカウントの種別を通知する必要がありま
す。[Production ExactTarget Account (本番 ExactTarget アカウント)] は、ほとんどの開発
者がアクセスでき、開発目的で使用するアカウントです。[Sandbox ExactTarget Account
273
第 21 章 ExactTarget API
(Sandbox ExactTarget アカウント)]は、一部の組織が購入する特殊なアカウントで、テ
ストのために本番アカウントと共に使用されます。選択するアカウントの種別が明確
でない場合は、[Production ExactTarget Account (本番 ExactTarget アカウント)] を選択します。
アプリケーションにリンクする ExactTarget アカウントの種別を選択したら、[Link to
Account (アカウントにリンク)] ボタンをクリックします。新規ブラウザウィンドウが
開き、Marketing Cloud のログイン画面が表示され、ユーザ名とパスワードの入力を求め
られます。既存のログイン情報がない場合は、必要に応じてユーザアカウントの作成
をシステム管理者に依頼してください。
メモ: Code@ExactTarget にログインするために使用したユーザ名とパスワードは
Marketing Cloud のログイン情報とは異なるため混同しないでください。
アプリケーションにアカウントの機能へのアクセス権
を付与する
ログインプロセスが完了すると、ウィザードの次のステップに自動的に移動します。
このステップでは、アプリケーションで使用する必要のあるアカウントの機能を App
Center に通知する必要があります。アプリケーションは、ここで指定するアカウント
の機能にのみアクセスできます。他のアプリケーション種別 (Marketing Cloud アプリケー
ションなど) の場合、Marketing Cloud アカウントでアプリケーションを使用するには、
アプリケーションのユーザにこれらの機能へのアクセス権も必要になります。
アプリケーションでは、メール、リスト、登録者、データ拡張の作成および変更、
メールの送信、追跡イベントデータの取得を行う必要があります。そのため、このス
テップでは、次のアカウントの機能および操作へのアクセス権をアプリケーションに
付与します。
• チャネル - メール: 参照、更新、送信
• 取引先責任者 - リストおよび登録者: 参照、更新
• データ - データ拡張: 参照、更新
• データ - 追跡イベント: 参照
274
第 21 章 ExactTarget API
仕上げ
ウィザードのこのステップが完了すると、概要画面が表示されます。問題がなけれ
ば、[Finish (完了)] をクリックします。
概要画面には、接続アプリケーションの OAuth クライアントログイン情報も表示され
ます。この情報は、他の Fuel API でアプリケーションを認証する OAuth トークンを取得
するために、Fuel の認証サービスで使用されます。
優待制限にも注意します。[COURTESY LIMIT (優待制限)] は、アプリケーションが実行可
能な API コール数の厳格な上限ではありません。アプリケーションで 1 日あたり 50,000
件を超える API コールを行う必要があっても、制限はされません。ただし、Fuel プラッ
トフォームでは、各アプリケーションの利用状況を監視し、意図的または偶然に
Marketing Cloud リソースを不正使用しているアプリケーションのレート制限や調整を行
うことができます。
275
第 21 章 ExactTarget API
メモ: 接続アプリケーションの OAuth クライアントログイン情報は、App Center
ウィザードの認証ステップで付与された、アカウントへの事前承認済みアクセス
権を表します。クライアントの秘密が公開してしまうとリンク済みアカウントに
誰でもフルアクセスできるようになるため、クライアント側で JavaScript を介して
クライアントの秘密を公開しないようにしてください。また、クライアントの秘
密がアプリケーションに安全に保存されていることを必ず確認するようにしてく
ださい。
いつでも App Center のメインウィンドウからアプリケーションの概要画面に戻ること
ができます。
これで、アプリケーションが Marketing Cloud アカウントに接続され、そのアカウント
への OAuth ログイン情報を取得できました。コードを作成しましょう。
アプリケーションの作成
salesforce.com ではアプリケーションの構築に PHP SDK を使用しますが、どの Fuel SDK も
共通するパターンを採用しているため、サンプルコードを他の SDK にかなり簡単に適
用できます。
276
第 21 章 ExactTarget API
PHP SDK をまだインストールしていない場合は、https://code.exacttarget.com/sdks からダウ
ンロードして、PHP SDK をワークスペースの sdk というサブディレクトリにインストー
ルします。SDK の README に記載されているとおりにすべての連動関係がインストール
されいてることを確認します。
SDK を設定するには、OAuth 認証情報を config.php に追加する必要があります (SDK
には、config.php の作成に使用できるテンプレートファイルが含まれています)。
config.php はサーバ側でホストされ、クライアントには公開されないため、クライ
アント ID とクライアントの秘密を config.php に含めるのが安全です。
return array(
'appsignature' => 'none',
'clientid' => 'YOUR_CLIENT_ID_FROM_APP_CENTER',
'clientsecret' => 'YOUR_CLIENT_SECRET_FROM_APP_CENTER',
'defaultwsdl' =>
'https://webservice.exacttarget.com/etframework.wsdl'
);
Fuel SDK を初期化する
これで PHP SDK が設定されたので、ET_Client オブジェクトをインスタンス化して
SDK を初期化します。
require('sdk/ET_Client.php');
$client = new ET_Client();
ET_Client オブジェクトは、すべての Fuel SDK の中心オブジェクトであり、
config.php で指定されたクライアント ID とクライアントの秘密を使用した OAuth ア
クセストークンの取得や更新など、さまざまなタスクを自動的に実行します。
277
第 21 章 ExactTarget API
プロファイル属性を作成する (登録者データモデルを
定義する)
次に、登録者の名を保持するプロファイル属性を作成して、その登録者へのメールを
パーソナライズできるようにします。SDK を使用してプロファイル属性を作成する方
法を次に示します。
$profileAttribute = new ET_ProfileAttribute();
$profileAttribute->authStub = $client;
$profileAttribute->props = array("Name" => "FirstName", "PropertyType"
=> "string", "Description" => "The subscriber's first name");
$response = $profileAttribute->post();
print_r($response);
これは、Fuel SDK オブジェクトとの一般的なやりとりで、すべての Fuel SDK に共通する
パターンを示しています。
1. やりとりするオブジェクト (この場合は ET_ProfileAttribute) をインスタン
ス化します。
2. オブジェクト ($profileAttribute->authStub = $client) の authStub
プロパティを使用して、ExactTarget アカウントコンテキストを指定します。
3. 操作を制御する適切なプロパティを設定します (この場合は FirstName という
プロファイル属性を作成します。これは文字列であり、登録者の名が含まれま
す)。
4. 取得、作成、更新、削除などの操作に応じて、REST に似た操作 (get、post、
patch、delete) を実行します。このセクションのこの例では、プロファイル
属性を作成するため、post を実行します。
278
第 21 章 ExactTarget API
次の例では、ブラウザでの PHP ファイルの読み込みの典型的な結果を示します。
ET_Configure Object
(
[status] => 1
[code] => 200
[message] =>
[results] => Array
(
[0] => stdClass Object
(
[StatusCode] => OK
[StatusMessage] => Success
[OrdinalID] => 0
[Object] => stdClass Object
(
[PartnerKey] =>
[ID] => 348977
[ObjectID] =>
[Name] => FirstName
[PropertyType] => string
[Description] => The subscriber's first
name
)
279
第 21 章 ExactTarget API
)
)
[request_id] =>
[moreResults] =>
)
これは、PHP SDK メソッド呼び出しに対する典型的な応答です。ここでは、StatusCode
と StatusMessage が示すように、コールが (願わくは) 成功したことだけに注目して
ください。
リストを作成する
次に、プロファイル属性の作成で使用したパターンと同じものを使用して、登録者を
保持するリストを作成します。
$list = new ET_List();
$list->authStub = $client;
$list->props = array("ListName" => "my subscribers");
$response = $list->post();
print_r($response);
次の例では、ブラウザでの PHP ファイルの読み込みの典型的な結果を示します。
ET_Post Object
(
280
第 21 章 ExactTarget API
[status] => 1
[code] => 200
[message] =>
[results] => Array
(
[0] => stdClass Object
(
[StatusCode] => OK
[StatusMessage] => Created List.
[OrdinalID] => 0
[NewID] => 1992264
[Object] => stdClass Object
(
[PartnerKey] =>
[ID] => 1992264
[ObjectID] =>
[ListName] => my subscribers
)
)
)
[request_id] =>
[moreResults] =>
281
第 21 章 ExactTarget API
)
ここでは、NewID プロパティに注目してください。オブジェクトが ExactTarget Marketing
Cloud で作成されると、一意の識別子がそのオブジェクトに割り当てられます。この
一意の識別子は、応答オブジェクトの NewID プロパティで確認できます。このオブ
ジェクトを後で参照するために、次のように変数にこの識別子の値を保存することが
できます。
$listID = $response->results[0]->NewID;
ここで、その値をメモします。次の API コールでこの値を使用します。
登録者をリストに追加する
リストを作成したら、登録者を作成し、先ほど作成したリストにその登録者を追加し
ます。ID プロパティには、リストを作成した後にメモした NewID の値を使用しま
す。FirstName プロパティには、メールアドレスを使用します。
<?php
require('sdk/ET_Client.php');
$client = new ET_Client();
$subscriber = new ET_Subscriber();
$subscriber->authStub = $client;
$subscriber->props = array("EmailAddress" =>
"YOUR_EMAIL_ADDRESS_GOES_HERE", "Lists" => array("ID" =>
"YOUR_LIST_ID_GOES_HERE"));
// specify profile attributes
282
第 21 章 ExactTarget API
$subscriber->props['Attributes'] = array(array('Name' => 'FirstName',
'Value' => 'YOUR_FIRST_NAME_GOES_HERE'));
$response = $subscriber->post();
アカウントで SubscriberKey が有効になっていると、props で SubscriberKey 属
性を指定しない限り前述のコードサンプルは動作しません。SubscriberKey につい
ての詳細は、http://help.exacttarget.com/en/documentation/exacttarget/subscribers/subscriber_key
を参照してください。
メールを作成する
次に、リストに送信するメールを作成します。
$email = new ET_Email();
$email->authStub = $client;
$emailBody = <<<EMAIL
<html>
<body>
<p>%%FirstName%%,</p>
<p>We're pretty sure you would love our products!</p>
<small>
<p>This email was sent by:</p>
283
第 21 章 ExactTarget API
<p>
%%Member_Busname%%
<br />
%%Member_Addr%%
<br />
%%Member_City%%, %%Member_State%%, %%Member_PostalCode%%
<br />
%%Member_Country%%
</p>
<a href="%%profile_center_url%%">Profile Center</a>
<br /></small>
<custom name="opencounter" type="tracking">
</body>
</html>
EMAIL;
$email->props = array("Name" => "my email", "CustomerKey" => "123",
"Subject" => "Hi %%FirstName%%, we think you will like this", "HTMLBody"
=> $emailbody, "IsHTMLPaste" => true);
284
第 21 章 ExactTarget API
$response = $email->post();
print_r($response);
この操作は、前の操作に比べてかなり複雑です。このコールを使用して、いくつかの
重要な概念と機能を示します。
• CustomerKey というプロパティを ET_Email オブジェクトに追加しました。この
プロパティは ExactTarget のすべてのオブジェクトに存在し、これを使用して独自の
識別子をオブジェクトに追加できます。これにより、ExactTarget と既存のインフラ
ストラクチャとの統合が簡単になります。
• メールを開く顧客は、重要なタッチポイントです。顧客が HTML メールをいつ開く
かを ExactTarget で追跡するため、<custom name="opencounter"
type="tracking"> タグをメール本文に追加しました。
• メール件名 (Subject プロパティ) とメール本文 (HTMLBody プロパティ) のどちら
にも置換文字列が含まれ、置換文字列名の前後の %% で示されます。置換文字列に
は、プロファイル属性でユーザ定義されるものもあれば (FirstName など)、
ExactTarget で自動的に解決されるものもあります。
• IsHTMLPaste というプロパティがあります。これを true に設定することで、
Marketing Cloud UI のユーザは HTML エディタのみを使用してコンテンツを編集できる
ようになります。デフォルト設定、および IsHTMLPaste を false に設定する場
合は、WYSIWYG エディタで編集を行いますが、編集するにはコンテンツでテンプ
レートフックを提供する必要があります。API のみのインテグレーションを行う場
合、IsHTMLPaste の値を指定する必要はありません。
置換文字列を使用してメールをパーソナライズする
ユーザ定義の置換文字列を使用すると、各受信者へのメールをパーソナライズできま
す。メール件名が適切であれば受信者がメールを開く確率が高くなるため、好結果の
顧客タッチポイントを作成するうえで、適切なメール件名にすることは非常に重要で
す。ExactTarget のメール件名は、置換文字列の使用 (「%%FirstName%%!さん、ご購入
ありがとうございます」など) を含め、さまざまな方法でパーソナライズできます。
受信者がメールを開くと、メールの内容によって受信者が応対するか (商品を購入す
るなど)、否か (登録解除するなど) が決まります。ExactTarget には置換文字列に加え、
285
第 21 章 ExactTarget API
AMPscript コンテンツスクリプト言語、HTTPGet コンテンツ取得、高度な動的コンテンツ
機能など、コンテンツをより関連性のあるものにするためのさまざまな機能が備えら
れています。
ExactTarget で自動的に解決される置換文字列により、商業電子メールの送信を対象と
する CAN-SPAM 法にコンテンツを確実に準拠させることができます。CAN-SPAM の準拠
に役立てるため、ExactTarget では、すべてのメールに次のパーソナライズ文字列を含
める必要があります。
%%Member_Busname%%
%%Member_Addr%%
%%Member_City%%
%%Member_State%%
%%Member_PostalCode%%
%%Member_Country%%
これらの置換文字列には、CAN-SPAM で求められる送信組織の物理的住所の要素が含ま
れ、アカウント情報に基づいて ExactTarget で自動的に埋め込まれます。
また、ExactTarget では、メールの受信者が今後の受信を拒否するかどうかなどの登録
設定を管理する、プロファイルセンターへのリンクをすべてのメールに含める必要が
あります。これらのプロファイルセンターは、ExactTarget で作成およびホストされま
す。CAN-SPAM には、次の置換文字列を含めるだけで準拠できます。
%%profile_center_url%%
リストにメールを送信する
これで、リストの作成、リストへの登録者の追加、リストに送信するメールの作成が
完了したので、最初のメールを送信する準備が整いました。
$response = new ET_Post($myclient, 'Send', array("List"=> array("ID"
=> "YOUR_LIST_ID_GOES_HERE"), "Email" => array("CustomerKey" =>
"123")));
286
第 21 章 ExactTarget API
print_r($response);
YOUR_LIST_ID_GOES_HERE と記されている場所に、リストを作成した後に保存したリス
ト ID を指定します。
この例では少し異なる SDK パターンを使用しており、メールオブジェクトでメソッド
をコールする代わりに、SDK メソッドを直接コールしています。
ページを再読み込みします。これまでどおり、NewID プロパティの値をメモしておい
てください。これは開始した送信の一意の識別子であり、その送信に関する概要統計
と未加工の個別統計の取得、送信状況の取得、送信の停止、再開、キャンセルに使用
できます。この NewID の値は、送信に関連付けられた開封イベントのリストに戻る
ために、次のセクションで使用します。
追跡イベントデータを取得する
ExactTarget からイベントデータを取得して、顧客タッチポイントの成功をさまざまな
方法で測定できます。ExactTarget では、送信ごとに各種イベントが収集されます。
送信に関連する配信イベントを使用すると、データ品質が適切であるかどうかを判断
できます。このイベントには 2 種類あり、SentEvent はメールが表示および送信され
たことを示し、BounceEvent はメールが同期または非同期で不達になった (配信され
なかった) ことを示します。
送信に関連するエンゲージメントイベントを使用すると、顧客がメールの内容にどの
ように応対したかを把握することができます。このイベントには 3 種類あり、
UnsubEvent はスパムに関する苦情、返信メール管理、またはプロファイルセンター
によって受信者がリストから登録解除したことを示し、OpenEvent は受信者がメー
ルを開いたことを示し (上記の追跡ピクセルを含む HTML メールで、受信者が画像の
ロードを許可した場合にのみ動作する)、ClickEvent は受信者がメール内のリンクを
クリックしたことを示します (ExactTarget でリンクがラップされている場合にのみ動作
する)。
次の例では、先ほど実行した送信のすべての SentEvent を取得し、それをブラウザウィ
ンドウまたはコンソールに出力します。
<?php
require('sdk/ET_Client.php');
287
第 21 章 ExactTarget API
$client = new ET_Client();
$openEvent = new ET_OpenEvent();
$openEvent->authStub = $client;
$openEvent->props = array("SubscriberKey", "EventType", "EventDate");
$openEvent->filter = array("Property" => "SendID", "SimpleOperator"
=> "equals", "Value" => array(YOUR_SEND_ID_GOES_HERE));
$response = $openEvent->get();
print_r($response);
?>
再度、YOUR_SEND_ID_GOES_HERE と記されている場所に、送信実行後に保存した送信 ID
を指定します。
次の例では、ブラウザで変更した PHP ファイルの読み込みの典型的な結果を示しま
す。
ET_Get Object
(
[status] => 1
[code] => 200
[message] =>
[results] => Array
(
288
第 21 章 ExactTarget API
[0] => stdClass Object
(
[PartnerKey] =>
[ObjectID] =>
[SubscriberKey] => [email protected]
[EventDate] => 2013-11-09T19:01:33
[EventType] => Open
)
)
[request_id] => 6816994f-125b-4932-9003-bc669c1ea7cc
[moreResults] =>
)
この例は、登録者キー [email protected] を持つ登録者が 2013 年 11 月 9 日、午後 7
時 1 分にメールを開封したことを示しています。後続のコールでは前回のコール以降
の開封イベントのみが返されます。
API の直接使用
SDK が使用不可であるか適切な解決策でない言語またはプラットフォームを使用して
いる場合、SDK を経由するのではなく、API を直接使用できます。
289
第 21 章 ExactTarget API
アクセストークンの取得
API ベースのインテグレーションでは、まずアクセストークンを取得します。アクセ
ストークンは、他の API コールを認証するために使用されます。アクセストークンを
取得するには、Fuel の認証サービスを使用します。次のコードサンプルに、HTTP POST
要求を使用してアクセストークンを取得する方法を示します。
POST https://auth.exacttargetapis.com/v1/requestToken
Content-Type: application/json
{
"clientId": "YOUR_CLIENT_ID_FROM_APP_CENTER",
"clientSecret": "YOUR_CLIENT_SECRET_FROM_APP_CENTER"
}
200 OK
{
"accessToken": "dfy3dsnqw3gre6e3pbatcr4s"
"expiresIn": 3600
}
アクセストークンは、accessToken プロパティに返されます。このトークンを Bearer
HTTP 認証スキームの Authorization ヘッダー項目で指定することで、他の API コー
ルを認証することができます。たとえば、次のようになります。
GET https://www.exacttargetapis.com/platform/v1/endpoints
Accept: application/json
Authorization: Bearer dfy3dsnqw3gre6e3pbatcr4s
290
第 21 章 ExactTarget API
Fuel アクセストークンは、ExactTarget の SOAP API を使用した認証にも使用できます。次
に、同じアクセストークンを使用した SOAP API での認証例を示します。
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:fueloauth xmlns="http://exacttarget.com"
xmlns:h="http://exacttarget.com">
dfy3dsnqw3gre6e3pbatcr4s
</h:fueloauth>
</s:Header>
[...]
</s:Envelope>
アクセストークンの更新
requestToken API コールに対する HTTP 応答の expiresIn プロパティに注目してく
ださい。Fuel アクセストークンは、発行されてから 1 時間後に期限切れになります。
期限切れのトークンを使用しようとすると、「401 Unauthorized HTTP (401 未認証
HTTP)」応答が返されます。この場合は、アクセストークンを更新する必要がありま
す。
API を直接使用する場合の重要な考慮事項
SDK を使用する代わりに API を直接使用して独自の OAuth トークン管理を行う場合、重
要な考慮事項が 2 つあります。
まず、新しいトークンは API コールを行うたびに要求しないようにします。各トーク
ンは 1 時間有効であるため、再利用してください。1 つの操作に対して API コールを 2
回行うのは非効率的であり、スロットルが発生する可能性があります。
次に、クライアントの秘密を保存する場合は、十分に注意してください。特に、モバ
イルデバイスは安全な環境ではないため、クライアントの秘密をモバイルアプリケー
291
第 21 章 ExactTarget API
ションに保存しないでください。代わりに、「認証コード」または「OAuth の暗黙的
付与」フローを使用することをお勧めします。
高度なパーソナライズ用のデータ拡張と AMPscript
の使用
このセクションでは、高度な Marketing Cloud テクノロジであるデータ拡張と AMPscript
の 2 つを使用して、メッセージをさらにパーソナライズして関連性を高めます。
データ拡張は、ほとんどすべてのデータ型の柔軟なテーブルであり、パーソナライズ
設定やセグメント化に使用したり、送信元データソースとして使用したりできます。
データ拡張は非常に強力な構造になっており、クラウドベースのマーケティングリ
レーショナルデータベースとみなすことができます。
AMPscript は Marketing Cloud のコンテンツスクリプト言語であり、メール、SMS メッセー
ジ、ランディングページのコンテンツをプログラムでパーソナライズするために使用
できます。AMPscript とデータ拡張は連動できるため、メッセージのデータ拡張から
データを読み取り、ランディングページのデータ拡張にデータを書き込むことができ
ます。
この例では、データ拡張を使用して商品に関する情報を保存し、その情報を使用して
前のセクションで送信したメールをさらにパーソナライズします。具体的には、登録
者の以前の購入パターンを使用して、関連性の高い商品をメールに記載し次回の購入
を促進します。
データ拡張を作成する
まず、Products というデータ拡張を作成して、商品に関する情報を保存します。こ
の例では、商品ごとに一意の識別子、名前、価格、画像 URL があります。
id
名前
価格
画像
...
...
...
...
292
第 21 章 ExactTarget API
では、SDK を使用してデータ拡張の作成を開始しましょう。
<?php
require('sdk/ET_Client.php');
$client = new ET_Client();
$de = new ET_DataExtension();
$de->authStub = $client;
$de->props = array("Name" => "Products", "CustomerKey" => "products");
// specify the data extension columns
$de->columns = array();
$de->columns[] = array("Name" => "id", "FieldType" => "Number",
"IsPrimaryKey" => "true", "IsRequired" => "true");
$de->columns[] = array("Name" => "name", "FieldType" =>
"Text","MaxLength" => "100");
$de->columns[] = array("Name" => "price", "FieldType" => "Decimal",
"Precision" => "18", "Scale" => "2");
$de->columns[] = array("Name" => "image", "FieldType" =>
"Text","MaxLength" => "100");
$response = $de->post();
?>
293
第 21 章 ExactTarget API
データ拡張にデータを取り込む
Products データ拡張を作成したら、一部の商品データをこのデータ拡張に追加しま
す。具体的には、Products データベースに次の 2 つの新しい行を追加します。
id
名前
価格
画像
1234
iPhone 5c
$99.95
http://bit.ly/H76rMz
5678
iPhone 5c case
$29.95
http://bit.ly/Hesctp
この 2 つの新しい行を作成してみましょう。
<?php
require('sdk/ET_Client.php');
$client = new ET_Client();
$deRow = new ET_DataExtension_Row();
$deRow->authStub = $client;
// specify the name of the data extension
$deRow->Name = "Products";
// specify the values of data extension row #1
$deRow->props = array("id" => "1234", "name" => "iPhone 5c", "price"
=> "99.95", "image" => "http://bit.ly/H76rMz");
294
第 21 章 ExactTarget API
$response = $deRow->post();
print_r($response);
// specify the values of data extension row #2
$deRow->props = array("id" => "5678", "name" => "iPhone 5c case",
"price" => "29.95", "image" => "http://bit.ly/Hesctp");
$response = $deRow->post();
print_r($response);
?>
上記の方法は、単一行または小規模なデータに対して定期更新でリアルタイムまたは
ほぼリアルタイムの更新を行う、小規模から中規模のデータに最適です。たとえば、
購入データが発生するごと、または定期的 (1 時間ごとなど) にデータを ExactTarget に送
信する場合は、API アプローチを用いることが理想的です。
他のシナリオでは、データ拡張へのデータ一括読み込みが必要です。たとえば、数百
万もの商品を定期的に ExactTarget に読み込む場合には、帯域幅や処理の観点から見て、
ファイルベースアプローチの方が効率的となることがあります。このような大量の
データをデータ拡張に一括読み込みするには、FTP サイトに置かれた圧縮ファイルを
インポートする方法が最も効率的です。
295
第 21 章 ExactTarget API
登録者データモデルを拡張する
次に、ここでは次回の購入に推奨する商品の ID を保存するために、別のプロファイル
属性を作成します。
<?php
require('sdk/ET_Client.php');
$client = new ET_Client();
$profileAttribute = new ET_ProfileAttribute();
$profileAttribute->authStub = $client;
$profileAttribute->props = array("Name" => "productID", "PropertyType"
=> "double", "Description" => "ID of next product recommendation");
$response = $profileAttribute->post();
print_r($response);
?>
実際の使用事例では、過去の購入を分析し、登録者ごとに次回の購入に含める、最も
関連性が高いと判断される商品の productID プロファイル属性を入力するバックグ
ラウンドプロセスが稼動している場合があります。この例では、productID プロファ
イル属性を手動で入力する必要があります。これを 5678 に設定してみます。
<?php
require('sdk/ET_Client.php');
296
第 21 章 ExactTarget API
$client = new ET_Client();
$subscriber = new ET_Subscriber();
$subscriber->authStub = $client;
$subscriber->props = array(array('Name' => 'FirstName', 'Value' =>
'YOUR_FIRST_NAME_GOES_HERE'));
$response = $subscriber->post();
print_r($response);
?>
AMPscript を使用してすべて処理する
最後に、プロファイル属性 productID を使用して Products データ拡張から商品に
関する詳細を読み取る AMPscript を含めるようにメールを更新し、それらの詳細をメー
ルメッセージに含めます。ここでは、既存のメールを更新するため、パッチを使用し
ます。
<?php
require('sdk/ET_Client.php');
$email = new ET_Email();
297
第 21 章 ExactTarget API
$email->authStub = $client;
$emailBody = <<<EMAIL
<html>
<body>
<p>%%FirstName%%,</p>
<p>We're pretty sure you would love the following product:</p>
<p>
<b>%%=Lookup("Products", "name", "id", productID)=%%</b>
<br />
<i>%%=Lookup("Products", "price", "id", productID)=%%</i>
</p>
<img src="%%=Lookup("Products", "image", "id", productID)=%%"
width="25%" />
<p>We appreciate your continued business!</p>
<small>
<p>This email was sent by:</p>
298
第 21 章 ExactTarget API
<p>
%%Member_Busname%%
<br />
%%Member_Addr%%
<br />
%%Member_City%%, %%Member_State%%, %%Member_PostalCode%%
<br />
%%Member_Country%%
</p>
<a href="%%profile_center_url%%">Profile Center</a>
<br />
</small>
<custom name="opencounter" type="tracking">
</body>
</html>
EMAIL;
// set the subject line and HTML email body
$email->props = array("CustomerKey" => "123", "Subject" => "Hi
%%FirstName%%, may we suggest for your next purchase...", "HTMLBody"
=> $emailBody);
299
第 21 章 ExactTarget API
// update the ET_Email object
$response = $email->patch();
print_r($response);
$response = new ET_Post($client, 'Send', array("List" => array("ID"
=> "YOUR_LIST_ID_GOES_HERE"), "Email" => array("CustomerKey" =>
"123")));
print_r($response);
?>
上記のメールで使用される AMPscript は、Lookup 関数です。Lookup 関数は、データ
拡張の単一行の単一項目値を返します。この例では、AMPscript は次のようになりま
す。
%%=Lookup("Products", "price", "id", productID)=%%
出力は、次のようになります。
29.95
この例では、Products データ拡張から price 項目の値を検索しています。Products
データ拡張には主キーが 1 つあり、Lookup 関数の最後の 2 つのパラメータによって、
その主キーの名前と値が指定されます。この例では、登録者のプロファイル属性
productID で指定された商品 ID データが、この主キーの値になります。
次のようなメールを受信します。
300
第 21 章 ExactTarget API
実際に操作してみる
ExactTarget テクノロジと概念をいくつか使用して、比較的高度なメールコミュニケー
ションの作成が完了しました。この練習問題には、よりパーソナライズされた有益な
顧客タッチポイントを作成するため、組織のデータを使用する独創的な方法が含まれ
ています。
このセクションで習得した多くの概念は、SMS などの他のチャネルでコンテンツをパー
ソナライズする場合にも活用できます。
301
第 21 章 ExactTarget API
リソース
この章の最新情報は、https://code.exacttarget.com/getting-started/ で確認してください。そ
の他の有益な情報には次の場所からアクセスできます。
一般的な開発者リソース
• Code@ExactTarget 開発者コミュニティ: https://code.exacttarget.com
• Code@ExactTarget App Center: https://code.exacttarget.com/appcenter
• Fuel API: https://code.exacttarget.com/api
• Fuel SDK: https://code.exacttarget.com/sdks
• Fuel UX: https://code.exacttarget.com/fuelux
• データ拡張とデータのリレーション:
http://help.exacttarget.com/en/documentation/exacttarget/subscribers/data_extensions_and_data_relationships
メールコミュニケーション
• ExactTarget メール開発者向けドキュメント: https://code.exacttarget.com/sdks
• ExactTarget メール製品ドキュメント: http://help.exacttarget.com/en/documentation/exacttarget
• ExactTarget メール製品情報: http://www.exacttarget.com/products/email-marketing
• メールコンテンツシンジケーション:
http://help.exacttarget.com/en/documentation/exacttarget/content/content_syndication
• メールカスタマイズの文字列:
http://help.exacttarget.com/en/documentation/exacttarget/content/personalization_strings
• AMPScript ドキュメント:
http://help.exacttarget.com/en/documentation/exacttarget/content/ampscript
SMS コミュニケーション
• MobileConnect 製品ドキュメント: http://help.exacttarget.com/en/documentation/mobileconnect/
• ExactTarget Marketing Cloud モバイル製品情報:
http://www.exacttarget.com/products/mobile-marketing
302
第 21 章 ExactTarget API
転送コミュニケーション
• MobilePush 開発者向けドキュメント: https://code.exacttarget.com/getting-started/mobilepush
• MobilePush 製品ドキュメント: http://help.exacttarget.com/en/documentation/mobilepush
• ExactTarget Marketing Cloud モバイル製品情報:
http://www.exacttarget.com/products/mobile-marketing
303
第 22 章
Radian6 API
Radian6 を使用すると、会社、商品、および競合他社に関する顧客の会話を聴き取り、
分析し、会話に参加することができます。
Radian6 API を使用して、Salesforce Marketing Cloud の機能を拡張できます。Radian6 API で
は、次のことができます。
• カスタムレポートを作成し、独自の視覚効果を設定する。
• トピックプロファイルから直接投稿データを抽出する。
• Radian6 ダッシュボードの視覚効果またはウィジェットからデータを抽出する。
• 投稿タグやソースタグなど、追加された投稿データにアクセスする。
• 人口統計、感情、エンティティなど、Radian6 Insights データにアクセスする。
次に、このデータを使用して、内部のカスタムレポート作成からアプリケーションや
サービスの価値向上にいたるまで、インテグレーションを促進できます。
サポートされるブラウザ
Radian6 では、次のブラウザがサポートされます。
• Mozilla® Firefox®
• Google Chrome™
• Microsoft® Internet Explorer®
• Apple® Safari®
以前のバージョンの Internet Explorer では Summary Dashboard がサポートされない場合が
あります。Internet Explorer 9 以上か、上記の別のブラウザを使用することをお勧めしま
す。
サポート対象の Salesforce のエディション
Radian6 では、次の Salesforce エディションをサポートしています。
305
第 22 章 Radian6 API
• Developer Edition
• Enterprise Edition
• Unlimited Edition
既存のSalesforceのお客様が上記のいずれかのエディションにアップグレードする場合
は、担当者にご連絡ください。
クイックスタート
Radian6 REST API は、ソーシャルメディア投稿と Radian6 アカウントのトピックプロファ
イルからのデータを取得、分析、変更します。
開始する前に、次の情報が入手できていることを確認してください。
• 有効なユーザ名とパスワード
• アプリケーションの一意のアプリケーションキー
まだアプリケーションキーがない場合は、営業担当者にお問い合わせください。
Radian6 API へのアクセスには、次のエンドポイントを使用できます。
開発エンドポイント
https://demo-api.radian6.com/socialcloud/v1/
アプリケーションを本番で実行する前に、すべての開発作業を開発エンドポイン
トで実行およびテストする必要があります。
本番エンドポイント
https://api.radian6.com/socialcloud/v1/
開発エンドポイントでのテストが完了したら、本番エンドポイントでアプリケー
ションを実行します。
現在この 2 つのエンドポイントのいずれかに対してしかアカウントがない場合、アカ
ウントをコピーして両方のエンドポイントで使用できるようにするには、
[email protected] までお問い合わせください。
Radian6 API の使用を開始するには、次の手順に従ってください。
1. API で認証します。
2. いずれかの API メソッドに基本的なコールを発行します。
3. Radian6 システムから何らかのデータを取得します。
306
第 22 章 Radian6 API
ステップ 1: API で認証する
コールを発行する前に API で認証する必要があります。
API が現在サポートしているのは、基本認証メカニズムのみです。後続の API コールで
使用する認証トークンを取得するには、最初に認証サービスに対してコールを実行す
る必要があります。
https://api-endpoint/auth/authenticate
このコールでは、認証チェックのための次の要求ヘッダーが返されます。
パラメータ
説明
auth_user
アカウントのユーザ名
auth_pass
プレーンテキストのパスワード
auth_appkey
ヘッダーパラメータに含める API キー
すべてのパラメータは必須です。認証が成功すると、基本的なユーザアカウント情報
とトークンタグが含まれる XML が次の形式で返されます。
<token>70d756801c703f3e78f81726c11b00249fb81770a446958b2577cd223811e</token>
このトークンを使用して、後続の API 要求を実行します。
<auth>
<token>e008252b4dce9b29c4c8155f0010cc8e128290b9e3ae99c8e9d15c
</token>
<UserDetails>
<user>
<userId>132972</userId>
<clientId>1226</clientId>
307
第 22 章 Radian6 API
<displayName>Joe User</displayName>
<emailAddress>[email protected]</emailAddress>
<packages />
</user>
<Packages>
<feature>
<featureId>1</featureId>
<description>Workflow</description>
</feature>
<feature>
<featureId>4</featureId>
<description>Admin Portal Full</description>
</feature>
<feature>
<featureId>6</featureId>
<description>Require PO Number</description>
</feature>
<feature>
<featureId>8</featureId>
<description>SENTIMENT</description>
</feature>
</Packages>
308
第 22 章 Radian6 API
</UserDetails>
</auth>
ステップ 2: メソッドへのコールを発行する
Radian6 API で認証が終了したら、API メソッドへのコールを発行します。
認証トークンと API アプリケーションキーを入手できたので、いずれかの API メソッド
をコールできます。データを取得するには、トピックプロファイルを使用する必要が
あるので、まずトピックのリストを取得しましょう。トピックのリストの取得に使用
するコールは、TopicService.fetchTopicList です。
https://api-endpoint/topics
他のすべてのコールと同様に、「ステップ 1: API で認証する」で取得した 2 つの要求
ヘッダー auth_token と auth_appkey を指定する必要があります。
トピックプロファイルのリストと関連情報が含まれる XML 応答を受け取ります。
XML 応答形式のサンプル
<topicFilters>
<topicFilter>
<name><![CDATA[2013 Candidates]]></name>
<public>1</public>
<status>1</status>
<estimateVolume>317900</estimateVolume>
<competeEnabled>0</competeEnabled>
<bCode></bCode>
309
第 22 章 Radian6 API
<creatorId>2</creatorId>
<creatorName>Chris Doe</creatorName>
<creatorEmail>[email protected]</creatorEmail>
<createDate>20080124</createDate>
<topicFilterId>232</topicFilterId>
<sentiment>0</sentiment>
<postTopicIgnoreStatus>-1</postTopicIgnoreStatus>
<inboundOnTopicLinksCount>0</inboundOnTopicLinksCount>
<number_queries>13</number_queries>
<filterGroups>
<filterGroup>
<filterGroupId>541</filterGroupId>
<name><![CDATA[Group 1]]></name>
<filterGroupTypeId>1</filterGroupTypeId>
<filterQueries>
<filterQuery>
<query>"John" AND "president"</query>
<filterQueryId>2031</filterQueryId>
<isExcludeQuery>false</isExcludeQuery>
</filterQuery>
<filterQuery>
<query>"Jane" AND "ceo"</query>
310
第 22 章 Radian6 API
<filterQueryId>2039</filterQueryId>
<isExcludeQuery>false</isExcludeQuery>
</filterQuery>
</filterQueries>
</filterGroup>
</filterGroups>
<sentimentQueries></sentimentQueries>
<includeSourceFilterList>
<filterIds></filterIds>
</includeSourceFilterList>
<excludeSourceFilterList>
<filterIds></filterIds>
</excludeSourceFilterList>
<includeAllSourceFilterList>
<filterIds></filterIds>
</includeAllSourceFilterList>
<languages></languages>
<mediaType></mediaType>
<projects></projects>
<regions></regions>
</topicFilter>
</topicFilters>
311
第 22 章 Radian6 API
ステップ 3: データを取得する
Radian6 API による認証が終わり、トピックのリストを取得したら、トピックのデータ
を取得できます。
次の例は、Radian6 システムからあるトピックについて過去 24 時間のうち最近の 100 項
目を取得する方法を示します。このデータの取得に使用するコールは、
DataService.fetchRecentTopicPosts です。
https://api-endpoint/data/topicdata/recent/{recentXhours}/{topics}
/{mediatypes}/{PageIndex}/{pageSize}
recentXHours
24 (過去 24 時間のデータ)
topics
232 (「ステップ 2: メソッドへのコールを発行する」のコールで取得したトピック
ID)
mediatypes
1,2,3,4 (LookupService.fetchMediaTypes で取得)
PageIndex
1 (最初のページ)
pageSize
100 (現在のページの全項目)
たとえば、開発エンドポイントへのコールは次のようになります。
https://sandbox-insights.radian6.com/socialcloud/v1/data/topicdata
/realtime/24/232/1,2,3,4/1/100
このコールは、一致する投稿のリストをデフォルトの並び順である publish_date
で並び替えて返します。結果セットの各項目は、<Article> タグで定義されます。
<radian6_RiverOfNews_export>
<report_date>Fri Oct 30 10:22:06 ADT 2009</report_date>
<user_name>Jane Smith</user_name>
312
第 22 章 Radian6 API
<RoN_sort_order>publishedDate</RoN_sort_order>
<article_count>1</article_count>
<article ID="1934621185">
<description charset="UTF-8">
<headline><![CDATA[ TWEET FROM: ACME]]>
</headline>
<author><![CDATA[ ACME]]>
</author>
<content><![CDATA[ The content of the Tweet]]>
</content>
</description>
<source><![CDATA[ TWEET FROM: ACME]]></source>
<host><![CDATA[ twitter.com]]></host>
<article_url> <![CDATA[
http://twitter.com/username/statuses/4735539663]]>
</article_url>
<media_provider>TWITTER</media_provider>
<media_type_id>8</media_type_id>
<spam_rating>TODO</spam_rating>
<publish_date>Oct 09, 2009 11:31 AM</publish_date>
<harvest_date>Oct 09, 2009 11:31 AM</harvest_date>
<PostDynamicsIteration>
313
第 22 章 Radian6 API
<PostDynamicsDefinition>
<fieldId>9</fieldId>
<label>Following</label>
<value>0</value>
<sortOrder>1</sortOrder>
</PostDynamicsDefinition>
<PostDynamicsDefinition>
<fieldId>8</fieldId>
<label>Followers</label>
<value>0</value>
<sortOrder>2</sortOrder>
</PostDynamicsDefinition>
<PostDynamicsDefinition>
<fieldId>10</fieldId>
<label>Updates</label>
<value>0</value>
<sortOrder>3</sortOrder>
</PostDynamicsDefinition>
<PostDynamicsDefinition>
<fieldId>21</fieldId>
<label>Sentiment</label>
<shortLabel>S</shortLabel>
314
第 22 章 Radian6 API
<sortOrder>4</sortOrder>
<value>15418,0</value>
<exceptionValue>15418,false</exceptionValue>
<reportValue>Neutral</reportValue>
<tooltip />
</PostDynamicsDefinition>
<reportFormatedData><![CDATA[ <span
style="font-weight:bold; color: #FF9900; font-size: 11pt"> Following:
</span>0 <span style="font-weight:bold; color: #FF9900; font-size:
11pt"> Followers:
</span>0 <span style="font-weight:bold; color: #FF9900; font-size:
11pt"> Updates: </span>0 <span style="font-weight:bold; color:
#FF9900; font-size: 11pt"> Sentiment: </span>Neutral ]]>
</reportFormatedData>
</PostDynamicsIteration>
</article>
</radian6_RiverOfNews_export>
サービスの使用
投稿、ユーザ、洞察、トピック、およびその他のデータにアクセスします。
このセクションでは、各サービスの一般的な操作について説明します。例の完全なリ
ストや応答の詳細は、http://socialcloud.radian6.com/docs/ のRadian6 API の
リファレンスを参照してください。
315
第 22 章 Radian6 API
Post サービス
Post サービスを使用すると、投稿へのユーザの割り当て、投稿に対するエンゲージメ
ント種別の設定、投稿へのタグの追加などの操作を実行できます。
コールは、30 秒以下の間隔で実行できます。
投稿の詳細を取得する
コンテンツ、タイトル、著者、公開日など、投稿の詳細を取得します。
GET /post
パラメータ
型
説明
auth_token
HeaderParam
必須。API で認証から返されるトークンが含ま
れる要求ヘッダー。
auth_appkey
HeaderParam
必須。アカウント固有のアプリケーション
キー。
url
PathParam
投稿の URL。
例
http://api.radian6.com/socialcloud/v1/post?url=http://twitter.com
/username/statuses/13...4
要求ヘッダー
GET /socialcloud/v1/post?url HTTP/1.1
Host: api.radian6.com
auth_token: NotARealToken
auth_appkey: NotARealAppKey
316
第 22 章 Radian6 API
応答ヘッダー
HTTP/1.1 200 OK
Date: Thu, 29 Sep 2011 17:17:16 GMT
Content-Type: application/xml
Content-Length: 705
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
応答
<?xml version="1.0" encoding="iso-8859-1"?>
<PostDetails>
<blogPost>
<Post>
<postId>12....</postId>
<title>
<![CDATA[Tweet from username (r6ts) ]]>
</title>
<author>
<![CDATA[username]]>
</author>
<content>
<![CDATA[]]>
317
第 22 章 Radian6 API
</content>
<publishedDate>1321898901000</publishedDate>
<link>
<![CDATA[http://twitter.com/username/statuses/13.....3]]>
</link>
<providerId>10</providerId>
<mediaTypeId>1</mediaTypeId>
<languageId>1</languageId>
<regionId>235</regionId>
<postStatusId>0</postStatusId>
</Post>
</blogPost>
<blog>
<blogId>44....7</blogId>
<title>
<![CDATA[Twitter / username]]>
</title>
<feed>
<![CDATA[http://twitter.com/statuses/user_timeline/username.atom]]>
</feed>
<link>
318
第 22 章 Radian6 API
<![CDATA[http://twitter.com/username]]>
</link>
<languageId>1</languageId>
<languageAccuracy>0.99</languageAccuracy>
</blog>
</PostDetails>
Post サービスのリソース
次のリストに、Post サービスで使用できる他の操作を示します。
操作
例
ユーザを投稿に割り
POST /post/workflow/assign/{postId}/{userId}
当てる
/{topicList}
投稿の分類を割り当
POST /post/workflow/classification/{postId}
てる
/{classificationTypeId}
投稿のエンゲージメ
POST /post/workflow/engagement/{postId}
ントを設定する
/{engagementTypeId}
投稿の感情を割り当
POST /post/workflow/sentiment/{postId}/{TopicId}
てる
/{sentimentValue}
投稿メモを追加する
POST /post/workflow/note/{postId}
319
第 22 章 Radian6 API
操作
例
投稿メモの返信を追
POST /post/workflow/notereply/{postId}
加する
投稿にタグを追加す
POST /post/workflow/tags/{postId}
る
スパムを切り替える
POST /post/workflow/toggleSpam/{postList}
/{topicList}/{spamValue}
投稿の動向を取得す
GET /post/metrics/{postId}
る
投稿ワークフローの
GET /post/workflow/updates/{epoch}/{postIdList}
更新を取得する
タグとメモを削除す
POST /post/workflow/removeTagsAndNotes
る
/{tagAndNoteIds}
子投稿の件数を取得
GET /v1/post/{parentPostId}/childcount
する
複数の投稿について
GET /v1/post/list/{parentPostIdList}/childcount
子投稿の件数を取得
する
auth_token および auth_appkey ヘッダーパラメータはすべてのコールに必須で
す。各操作についての詳細は、Radian6 API ドキュメントのPost サービスのリファレンス
を参照してください。
User サービス
User サービスを使用すると、ユーザ詳細とそのダッシュボードの取得などの操作を実
行できます。
320
第 22 章 Radian6 API
コールは、30 秒以下の間隔で実行できます。
ユーザを取得する
要求を行っているユーザの基本情報を返します。
GET /user
パラメータ
型
説明
auth_token
HeaderParam
必須。API で認証から返されるトークンが含ま
れる要求ヘッダー。
auth_appkey
HeaderParam
必須。アカウント固有のアプリケーション
キー。
例
http://api.radian6.com/socialcloud/v1/user
要求ヘッダー
GET /socialcloud/v1/smm/user HTTP/1.1
Host: api.radian6.com
auth_token: NotARealToken
auth_appkey: NotARealAppKey
応答ヘッダー
HTTP/1.1 200 OK
Date: Thu, 29 Sep 2011 17:17:16 GMT
Content-Type: application/xml
321
第 22 章 Radian6 API
Content-Length: 705
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
応答
<user>
<userId>538</userId>
<clientId>1</clientId>
<displayName>
<![CDATA[John Doe]]>
</displayName>
<emailAddress>[email protected]</emailAddress>
<timezone>GMT</timezone>
</user>
User サービスのリソース
次のリストに、User サービスで使用できるその他の操作を示します。
操作
例
ユーザの詳細を取得 GET /socialcloud/v1/user/details
する
クライアントを取得 GET /client
する
322
第 22 章 Radian6 API
操作
例
ダッシュボードウィ GET /user/dashboard
ジェットを取得する
アバターを設定する GET /user/avatar
auth_token および auth_appkey ヘッダーパラメータはすべてのコールに必須で
す。各操作についての詳細は、Radian6 API ドキュメントのUser サービスのリファレン
スを参照してください。
Insight サービス
Insight サービスを使用すると、insights の集計や insightTypes の取得などの操作を実行で
きます。
insightTypes を取得する
insights パッケージの関連付けられた insightTypes のリストを取得します。クライアント
には、指定されたトピックプロファイルへのアクセス権が必要です。また、トピック
プロファイルは指定された insights パッケージに登録されている必要があります。
GET /socialcloud/v1/insights/insightTypes
パラメータ
型
説明
auth_token
HeaderParam
必須。API で認証から返されるトークンが含ま
れる要求ヘッダー。
auth_appkey
HeaderParam
必須。アカウント固有のアプリケーション
キー。
packageId
QueryParam
insightTypes のリストの取得対象である insights
パッケージの ID。
topicProfileId QueryParam
指定された insights パッケージに登録されてい
るトピックプロファイルの ID。
323
第 22 章 Radian6 API
例
http://api.radian6.com/socialcloud/v1/insights/insightTypes
要求ヘッダー
GET
/socialcloud/v1/insights/insightTypes?packageId=1...2&topicProfileId=1...2
HTTP/1.1
Host: api.radian6.com
auth_token: NotARealToken
auth_appkey: NotARealAppKey
応答ヘッダー
HTTP/1.1 200 OK
Date: Mon, 05 Dec 2011 14:24:31 GMT
Server: Apache-Coyote/1.1
Content-Type: application/xml
Content-Length: 135
応答
<insightTypes>
<insightType>
<dataDescriptor>multi-value</dataDescriptor>
<description>Retweeted usernames</description>
<displayName>Retweeted Usernames</displayName>
324
第 22 章 Radian6 API
<isPrivacyRelated>false</isPrivacyRelated>
<name>retweet_username</name>
<objectId>4d6...bbb</objectId>
<providerName>radian6</providerName>
</insightType>
...
</insightTypes>
Insight サービスのリソース
次のリストに、Insight サービスで使用できる他の操作を示します。
操作
insights を集計する
例
POST /socialcloud/v1/insights
/aggregateInsightsByTopic
パッケージ登録を取
GET /socialcloud/v1/insights/packageSubscriptions
得する
検索条件値を取得す
GET /socialcloud/v1/insights/fetchFilterValues
る
/{topicFilterId}
ソース insights を取
得する
GET /socialcloud/v1/insights/fetchInsightsBySource
/{topicProfileId}/{blogIds}/{providers}
325
第 22 章 Radian6 API
auth_token および auth_appkey ヘッダーパラメータはすべてのコールに必須で
す。各操作についての詳細は、Radian6 API ドキュメントのInsight サービスのリファレン
スを参照してください。
Topic サービス
Topic サービスを使用すると、トピックプロファイル、検索条件グループ、検索条件ク
エリの作成などの操作を実行できます。
トピックプロファイルを作成または更新する
トピックを作成または更新します。
POST /topics/createTP/{topicId}/{name}/{isPublic}/{mediatypes}
/{languages}/{regions}
パラメータ
型
説明
auth_token
HeaderParam
必須。API で認証から返されるトークンが含ま
れる要求ヘッダー。
auth_appkey
HeaderParam
必須。アカウント固有のアプリケーション
キー。
topicId
PathParam
トピックの一意の ID (更新時に必須)
name
PathParam
トピック条件の表示名
isPublic
PathParam
トピックが公開か非公開かを示す整数値
mediatypes
PathParam
トピックの有効なメディアタイプを示すカンマ
区切りリスト
languages
PathParam
トピックの有効な言語を示すカンマ区切りリス
ト
regions
PathParam
トピックの有効な地域を示すカンマ区切りリス
ト
326
第 22 章 Radian6 API
パラメータ
型
説明
billingCode
QueryParam
トピックの請求先コード。デフォルトは空の文
字列です。
isTrial
QueryParam
トピックがトライアルかどうかを示す整数値。
デフォルトは 1 です。
例
http://api.radian6.com/socialcloud/v1/topics/createTP/1/My Topic/1/8/1/2
要求ヘッダー
GET /socialcloud/v1/topics/createTP/{topicId}/{name}/{isPublic}
/{mediatypes}/{languages}/{regions} HTTP/1.1
Host: api.radian6.com
auth_token: NotARealToken
auth_appkey: NotARealAppKey
応答ヘッダー
HTTP/1.1 200 OK
Date: Thu, 29 Sep 2011 17:17:16 GMT
Content-Type: application/xml
Content-Length: 705
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
327
第 22 章 Radian6 API
応答
<topicFilter>
<name>
<![CDATA[My Topic]]>
</name>
<public>0</public>
<status>2</status>
<estimateVolume>-1</estimateVolume>
<competeEnabled>0</competeEnabled>
<topicFilterTypeId>1</topicFilterTypeId>
<bCode>
<![CDATA[]]>
</bCode>
<creatorId>538</creatorId>
<creatorName>
<![CDATA[Jane Smith]]>
</creatorName>
<creatorEmail>Jane.Smith@...</creatorEmail>
<topicFilterId>3...3</topicFilterId>
<inboundOnTopicLinksCount>0</inboundOnTopicLinksCount>
<languages/>
<mediaType>8,12,14,13,11,10,9,5,2,1,16,4</mediaType>
328
第 22 章 Radian6 API
<projects/>
<regions/>
<deactivationDate>null</deactivationDate>
<evp>false</evp>
<topicFilterTier>
<topicFilterTierId>-1</topicFilterTierId>
<name/>
<lowerTrafficLimit>-1</lowerTrafficLimit>
<upperTrafficLimit>-1</upperTrafficLimit>
</topicFilterTier>
<number_queries>0</number_queries>
<filterGroups>
<filterGroup>
<filterGroupId>2...9</filterGroupId>
<name>
<![CDATA[Group 1]]>
</name>
<filterGroupTypeId>1</filterGroupTypeId>
<filterQueries/>
</filterGroup>
</filterGroups>
<sentimentQueries/>
329
第 22 章 Radian6 API
<includeSourceFilterList>
<filterIds/>
</includeSourceFilterList>
<excludeSourceFilterList>
<filterIds/>
</excludeSourceFilterList>
<includeAllSourceFilterList>
<filterIds/>
</includeAllSourceFilterList>
</topicFilter>
Topic サービスのリソース
次のリストに、Topic サービスで使用できる他の操作を示します。
操作
例
複数のトピックプロ GET /topics
ファイルを取得する
トピックプロファイ GET /topics/{topicId}
ルを取得する
トピックプロファイ GET /topics/usage
ルの使用状況を取得
する
トピックプロファイ POST /topics/remove/{topicId}
ルを削除する
330
第 22 章 Radian6 API
操作
例
ソース検索条件の関 POST /topics/{topicId}/sourcefilters
連付けを作成する
複数の検索条件グ
ループを取得する
GET /topics/{topicId}/filterGroups
検索条件グループを GET /topics/{topicId}/filterGroups/{filterGroupId}
取得する
ソース検索条件を取 GET /topics/{topicId}/sourcefilters
得する
検索条件グループを
DELETE /topics/{topicId}/filterGroups
削除する
/{filterGroupId}
検索条件グループを POST /topics/{topicId}/filterGroups
作成する
検索条件グループを PUT /topics/{topicId}/filterGroups/{filterGroupId}
更新する
複数の検索条件クエ
GET /topics/{topicId}/filterGroups
リを取得する
/{filterGroupId}/filterQueries
検索条件クエリを作
GET /topics/{topicId}/filterGroups
成する
/{filterGroupId}/filterQueries
検索条件クエリを取
GET /topics/{topicId}/filterGroups
得する
/{filterGroupId}/filterQueries/{filterQueryId}
331
第 22 章 Radian6 API
操作
例
検索条件クエリを削
DELETE /topics/{topicId}/filterGroups
除する
/{filterGroupId)/filterQueries/{filterQueryId}
Insight 登録ウィンド GET /topics/{topicId}/subscriptionWindow
ウを取得する
auth_token および auth_appkey ヘッダーパラメータはすべてのコールに必須で
す。各操作についての詳細は、Radian6 API ドキュメントのTopic サービスのリファレン
スを参照してください。
Data サービス
Data サービスを使用すると、投稿やトピック比較データの取得などの操作を実行でき
ます。
投稿データを取得する
特定のクエリパラメータに一致する投稿を取得します。
GET /data/topicdata/realtime/{recentXhours}/{topics}/{mediatypes}
/{pageIndex}/{pageSize}
パラメータ
型
説明
auth_token
HeaderParam
必須。API で認証から返されるトークンが含ま
れる要求ヘッダー。
auth_appkey
HeaderParam
必須。アカウント固有のアプリケーション
キー。
recentXhours
PathParam
さかのぼる時間数。たとえば、これを 48 に設
定すると、過去 2 日以内のすべての投稿が返さ
332
第 22 章 Radian6 API
パラメータ
型
説明
れます。公開日を参照して、応答内で返しま
す。
topics
PathParam
投稿の取得対象となるトピックプロファイル
ID のカンマ区切りリスト。
mediaTypes
PathParam
返す投稿の取得元となるメディアタイプのカン
マ区切りリスト。
pageIndex
PathParam
返すデータのページを指定します。
pageSize
PathParam
1 ページに返す投稿の数。
例
http://api.radian6.com/socialcloud/v1/data/topicdata/realtime
/2/3..9/1,2,4,5,8,10,9,11,12,13,14,16/1/20?includeWorkflow=1&includeSpam=0
&merged=1&token=1321987774350&extendedMediaTypes=2,3,4
要求ヘッダー
GET /socialcloud/v1/data/topicdata/realtime/{recentXhours}/{topics}
/{mediatypes}/{pageIndex}/{pageSize} HTTP/1.1
Host: api.radian6.com
auth_token: NotARealToken
auth_appkey: NotARealAppKey
応答ヘッダー
HTTP/1.1 200 OK
333
第 22 章 Radian6 API
Date: Thu, 29 Sep 2011 17:17:16 GMT
Content-Type: application/xml
Content-Length: 705
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
応答
<?xml version="1.0" encoding="UTF-8"?>
<radian6_RiverOfNews_export>
<report_date>2012-07-11 02:24:04 +1200</report_date>
<user_name>Jane.Smith@...</user_name>
<RoN_sort_order>publishedDate</RoN_sort_order>
<article_count>2</article_count>
<total_article_count>101</total_article_count>
<article ID="2...9">
<description charset="UTF-8">
<headline/>
<author fbid="-1" externalId="3...2"/>
<author_full_name />
<recipient/>
<content/>
<external_id>2...73</external_id>
334
第 22 章 Radian6 API
<parentExternalId>2...70</parentExternalId>
</description>
<avatar/>
<source/>
<host>
<![CDATA[twitter.com]]>
</host>
<article_url>
<![CDATA[2...73]]>
</article_url>
<media_provider>TWITTER</media_provider>
<media_type_id>8</media_type_id>
<language_id>16</language_id>
<spam_rating>0</spam_rating>
<publish_date epoch="1341901361000">2012-07-10 18:22:41
+1200</publish_date>
<harvest_date epoch="1341901379000">2012-07-10 18:22:59
+1200</harvest_date>
<PostInsights>
<PostInsight>
<Provider>
<![CDATA[provider_name]]>
</Provider>
335
第 22 章 Radian6 API
<Type>
<![CDATA[type_name]]>
</Type>
<Value>
<!CDATA[some_value]]>
</Value>
</PostInsight>
</PostInsights>
<SourceInsights>
<SourceInsight>
<Provider>
<![CDATA[provider_name]]>
</Provider>
<Type>
<![CDATA[type_name]]>
</Type>
<Value>
<![CDATA[some_value]]>
</Value>
<SourceInsight>
</SourceInsights>
<PostDynamicsIteration>
336
第 22 章 Radian6 API
<PostDynamicsDefinition>
<fieldId>9</fieldId>
<label>Following</label>
<value/>
<sortOrder>1</sortOrder>
</PostDynamicsDefinition>
<PostDynamicsDefinition>
<fieldId>8</fieldId>
<label>Followers</label>
<value/>
<sortOrder>2</sortOrder>
</PostDynamicsDefinition>
<PostDynamicsDefinition>
<fieldId>10</fieldId>
<label>Updates</label>
<value/>
<sortOrder>3</sortOrder>
</PostDynamicsDefinition>
<PostDynamicsDefinition>
<fieldId>21</fieldId>
<label>Sentiment</label>
<shortLabel>S</shortLabel>
337
第 22 章 Radian6 API
<sortOrder>4</sortOrder>
<value/>
<exceptionValue>2860,false</exceptionValue>
<reportValue>Neutral</reportValue>
<tooltip/>
</PostDynamicsDefinition>
<reportFormatedData/>
</PostDynamicsIteration>
</article>
<article ID="252359343">
<description charset="UTF-8">
<headline>
<![CDATA[Post from Facebook user]]>
</headline>
<author fbid="1769972299" externalId="1769972299">
<![CDATA[Facebook user]]>
</author>
<recipient>
<![CDATA[None]]>
</recipient>
<content>
<![CDATA[Facebook post content...]]>
338
第 22 章 Radian6 API
</content>
<external_id>17...9_22...4</external_id>
</description>
<source ID="1...2">
<![CDATA[Post from Facebook user]]>
</source>
<host>
<![CDATA[www.facebook.com]]>
</host>
<article_url>
<![CDATA[http://www.facebook.com/permalink.php?story_fbid=22...4&id=17...9]]>
</article_url>
<media_provider>facebook.com Discussions</media_provider>
<media_type_id>12</media_type_id>
<language_id>1</language_id>
<spam_rating>0</spam_rating>
<publish_date epoch="1341886037000">2012-07-10 14:07:17
+1200</publish_date>
<harvest_date epoch="1341886905000">2012-07-10 14:21:45
+1200</harvest_date>
<PostDynamicsIteration>
<PostDynamicsDefinition>
339
第 22 章 Radian6 API
<fieldId>21</fieldId>
<label>Sentiment</label>
<shortLabel>S</shortLabel>
<sortOrder>1</sortOrder>
<value>
<![CDATA[2860,0]]>
</value>
<exceptionValue>2860,false</exceptionValue>
<reportValue>Neutral</reportValue>
<tooltip/>
</PostDynamicsDefinition>
<reportFormatedData>
<![CDATA[<span style="font-weight:bold; color: #FF9900;
font-size: 11pt"> Sentiment: </span>Neutral ]]>
</reportFormatedData>
</PostDynamicsIteration>
</article>
</radian6_RiverOfNews_export>
この操作のパラメータの完全なリストについては、Radian6 API ドキュメントの「投稿
データを取得する」を参照してください。
Data サービスのリソース
次のリストに、Data サービスで使用できる他の操作を示します。
340
第 22 章 Radian6 API
操作
例
範囲を指定してデー
GET /data/topicdata/realtime/{daterangeStart}
タを取得する
/{daterangeEnd}/{topics}/{mediatypes}/{pageIndex}/{pageSize}
タグクラウドデータ
GET /data/tagclouddata/{recentXhours}/{topics}
を取得する
/{mediatypes}/{advancedQueryFilters}
範囲を指定してタグ
GET /data/tagclouddata/{daterangeStart}
クラウドデータを取
得する
/{daterangeEnd}/{topics}/{mediatypes}/{advancedQueryFilters}
トピック一致データ
GET /data/comparisondata/{recentXhours}/{topics}
を取得する
/{mediatypes}/{segmentation}/{countBy}
範囲を指定してト
GET /data/comparisondata/{daterangeStart}
ピック一致データを
取得する
/{daterangeEnd}/{topics}/{mediatypes}/{segmentation}/{countBy}
ウィジェットデータ
GET /data/widget/{widgetId}
を取得する
auth_token および auth_appkey ヘッダーパラメータはすべてのコールに必須で
す。各操作についての詳細は、Radian6 API ドキュメントのデータサービスのリファレ
ンスを参照してください。
Blog サービス
Blog サービスを使用すると、特定サイトの投稿のリストを取得したり、サイトにメモ
を追加するなどの操作を実行できます。
341
第 22 章 Radian6 API
ブログの詳細を取得する
ワークフローの詳細を含む、特定サイトの投稿のリストを取得します。
GET /blog/workflow/{blogId}/{topicId}
パラメータ
型
説明
auth_token
HeaderParam
必須。API で認証から返されるトークンが含ま
れる要求ヘッダー。
auth_appkey
HeaderParam
必須。アカウント固有のアプリケーション
キー。
blogId
PathParam
投稿の取得対象のブログ ID。
topicId
PathParam
トピック ID のカンマ区切りリスト。
maxPostCount
QueryParam
要求ごとに返す投稿の総数。
pageNum
QueryParam
投稿を返すページのインデックス。たとえば、
要求に対する投稿の総数が (maxPostCount パラ
メータで指定された) 投稿の最大数を超えた場
合、現在の要求で返されない超過分の投稿を取
得するためにページ番号を増分できます。
例
http://api.radian6.com/socialcloud/v1/blog/workflow/5...5/2...7
要求ヘッダー
GET /socialcloud/v1/blog/workflow/{blogId}/{topicId} HTTP/1.1
Host: api.radian6.com
auth_token: NotARealToken
auth_appkey: NotARealAppKey
342
第 22 章 Radian6 API
応答ヘッダー
HTTP/1.1 200 OK
Date: Thu, 29 Sep 2011 17:17:16 GMT
Content-Type: application/xml
Content-Length: 705
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
応答
<?xml version="1.0" encoding="UTF-8"?>
<radian6_RiverOfNews_export>
<report_date>2012-07-11 02:24:04 +1200</report_date>
<user_name>Jane.Smith@...</user_name>
<RoN_sort_order>publishedDate</RoN_sort_order>
<article_count>1</article_count>
<total_article_count>1</total_article_count>
<article ID="2...3">
<description charset="UTF-8">
<headline>
<![CDATA[Post from Facebook user]]>
</headline>
<author fbid="17...9" externalId="17...9">
343
第 22 章 Radian6 API
<![CDATA[Facebook user]]>
</author>
<recipient>
<![CDATA[None]]>
</recipient>
<content>
<![CDATA[Facebook post content...]]>
</content>
<external_id>17...9_22...4</external_id>
</description>
<source ID="1...2">
<![CDATA[Post from Facebook user]]>
</source>
<host>
<![CDATA[www.facebook.com]]>
</host>
<article_url>
<![CDATA[http://www.facebook.com/permalink.php?story_fbid=22...4&id=17...9]]>
</article_url>
<media_provider>facebook.com Discussions</media_provider>
<media_type_id>12</media_type_id>
344
第 22 章 Radian6 API
<language_id>1</language_id>
<spam_rating>0</spam_rating>
<publish_date epoch="1341886037000">2012-07-10 14:07:17
+1200</publish_date>
<harvest_date epoch="1341886905000">2012-07-10 14:21:45
+1200</harvest_date>
<PostDynamicsIteration>
<PostDynamicsDefinition>
<fieldId>21</fieldId>
<label>Sentiment</label>
<shortLabel>S</shortLabel>
<sortOrder>1</sortOrder>
<value>
<![CDATA[2860,0]]>
</value>
<exceptionValue>2860,false</exceptionValue>
<reportValue>Neutral</reportValue>
<tooltip/>
</PostDynamicsDefinition>
<reportFormatedData>
<![CDATA[<span style="font-weight:bold; color: #FF9900;
font-size: 11pt"> Sentiment: </span>Neutral ]]>
</reportFormatedData>
</PostDynamicsIteration>
345
第 22 章 Radian6 API
</article>
</radian6_RiverOfNews_export>
Blog サービスのリソース
次のリストに、Blog サービスで使用できる他の操作を示します。
操作
例
サイトにメモを追加 POST /blog/workflow/note/{blogIdList}
する
投稿 ID を指定して
メモを追加する
POST /blog/workflow/noteByPostId/{blogPostId}
投稿 ID を指定して
タグを追加する
POST /blog/workflow/tagsByPostId/{blogPostId}
サイト総計値を取得 GET /blog/metrics/{siteId}/{topicId}
する
タグ付けされたブロ GET /blog/sourcetagged/{tags}
グを取得する
タグとメモを削除す
POST /blog/workflow/removeTagsAndNotes
る
/{tagAndNoteIds}
auth_token および auth_appkey ヘッダーパラメータはすべてのコールに必須で
す。各操作についての詳細は、Radian6 API ドキュメントのBlog サービスのリファレン
スを参照してください。
Authentication サービス
Authentication サービスを使用すると、Radian6 システムでユーザを認証できます。
346
第 22 章 Radian6 API
応答で認証トークンが返されます。この認証トークンは、auth_token という要求
ヘッダーとして後続の要求に使用します。すべての要求に auth_appkey も指定する
必要があります。
GET /socialcloud/v1/auth/authenticate
パラメータ
型
説明
auth_user
HeaderParam
必須。ユーザ名が含まれる要求ヘッダー。
auth_pass
HeaderParam
必須。プレーンテキストのパスワードが含まれ
る要求ヘッダー。
auth_token
HeaderParam
必須。API で認証から返されるトークンが含ま
れる要求ヘッダー。
auth_appkey
HeaderParam
必須。アカウント固有のアプリケーション
キー。
fields
QueryParam
userdetails や clientattributes など、
返す要素のカンマ区切りリスト。
例
https://api.radian6.com/socialcloud/v1/auth/authenticate
?fields=userdetails,clientattributes
要求ヘッダー
GET /socialcloud/v1/auth/authenticate HTTP/1.1
Host: api.radian6.com
auth_user: mikemullen
auth_pass: NotARealPassword
auth_appkey: NotARealAppKey
347
第 22 章 Radian6 API
応答ヘッダー
HTTP/1.1 200 OK
Date: Thu, 29 Sep 2011 17:17:16 GMT
Content-Type: application/xml
Content-Length: 705
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
応答
<auth>
<token>b65e06d1b5383...</token>
<UserDetails>
<user>
<userId>12345</userId>
<clientId>99</clientId>
<displayName><![CDATA[Mike Mullen]]></displayName>
<emailAddress>Mike.Mullen@...</emailAddress>
<timezone>GMT</timezone>
<packages></packages>
<userRoleId>1</userRoleId>
<createdDate>Jun 22, 2010 05:18 PM</createdDate>
<enabled>true</enabled>
348
第 22 章 Radian6 API
<aihUsers><aihUser>
<userKey>84ba97...</userKey>
<registerDate>2010</registerDate>
<type>1</type>
</aihUser></aihUsers>
</user>
<avatar
userId="12345"><![CDATA[http://path-to-avatar-image.jpg]]></avatar>
<Packages></Packages>
<ClientAttributes>
<attribute>
<id>12</id>
<description>IDLE_TIMEOUT</description>
<value>10800000</value>
</attribute>
...
</ClientAttributes>
</UserDetails>
</auth>
Lookup サービス
Lookup サービスを使用すると、メディアタイプ、言語、ユーザ、ワークフロー項目の
リストの取得などの操作を実行できます。
349
第 22 章 Radian6 API
メディアタイプを取得する
有効なメディアタイプのリストを取得します。メディアタイプは、Radian6 API 内のソー
シャルメディア投稿の種別とソースを指示するために使用します。メディアタイプを
使用して、Analysis Dashboard (Topic Profile Configurations) 内のソース検索条件を作成した
り、Data サービスのコールで結果を絞り込んだりできます。このコールは、システム
内のすべてのメディアタイプの名前と ID を表示します。
GET /lookup/mediaproviders
パラメータ
型
説明
auth_token
HeaderParam
必須。API で認証から返されるトークンが含ま
れる要求ヘッダー。
auth_appkey
HeaderParam
必須。アカウント固有のアプリケーション
キー。
例
http://api.radian6.com/socialcloud/v1/lookup/mediaproviders
要求ヘッダー
GET /socialcloud/v1/lookup/mediaproviders HTTP/1.1
Host: api.radian6.com
auth_token: NotARealToken
auth_appkey: NotARealAppKey
応答ヘッダー
HTTP/1.1 200 OK
Date: Thu, 29 Sep 2011 17:17:16 GMT
350
第 22 章 Radian6 API
Content-Type: application/xml
Content-Length: 705
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
応答
<?xml version="1.0" encoding="utf-8"?>
<MediaTypeList>
<MediaTypeItem>
<mediaTypeId>1</mediaTypeId>
<mediaTypeName>Blogs</mediaTypeName>
<displayOrder>1</displayOrder>
</MediaTypeItem>
<MediaTypeItem>
<mediaTypeId>2</mediaTypeId>
<mediaTypeName>Videos</mediaTypeName>
<displayOrder>2</displayOrder>
</MediaTypeItem>
<MediaTypeItem>
<mediaTypeId>4</mediaTypeId>
<mediaTypeName>Images</mediaTypeName>
<displayOrder>3</displayOrder>
351
第 22 章 Radian6 API
</MediaTypeItem>
<MediaTypeItem>
<mediaTypeId>5</mediaTypeId>
<mediaTypeName>Mainstream News</mediaTypeName>
<displayOrder>4</displayOrder>
</MediaTypeItem>
<MediaTypeItem>
<mediaTypeId>8</mediaTypeId>
<mediaTypeName>MicroMedia</mediaTypeName>
<displayOrder>5</displayOrder>
</MediaTypeItem>
<MediaTypeItem>
<mediaTypeId>10</mediaTypeId>
<mediaTypeName>Forums</mediaTypeName>
<displayOrder>6</displayOrder>
</MediaTypeItem>
<MediaTypeItem>
<mediaTypeId>9</mediaTypeId>
<mediaTypeName>Forum Replies</mediaTypeName>
<displayOrder>7</displayOrder>
</MediaTypeItem>
<MediaTypeItem>
352
第 22 章 Radian6 API
<mediaTypeId>11</mediaTypeId>
<mediaTypeName>Comments</mediaTypeName>
<displayOrder>8</displayOrder>
</MediaTypeItem>
<MediaTypeItem>
<mediaTypeId>12</mediaTypeId>
<mediaTypeName>Facebook</mediaTypeName>
<displayOrder>9</displayOrder>
</MediaTypeItem>
<MediaTypeItem>
<mediaTypeId>13</mediaTypeId>
<mediaTypeName>Aggregator</mediaTypeName>
<displayOrder>10</displayOrder>
</MediaTypeItem>
<MediaTypeItem>
<mediaTypeId>14</mediaTypeId>
<mediaTypeName>Buy/Sell</mediaTypeName>
<displayOrder>11</displayOrder>
</MediaTypeItem>
<MediaTypeItem>
<mediaTypeId>16</mediaTypeId>
<mediaTypeName>MySpace</mediaTypeName>
353
第 22 章 Radian6 API
<displayOrder>13</displayOrder>
</MediaTypeItem>
</MediaTypeList>
Lookup サービスのリソース
次のリストに、Lookup サービスで使用できる他の操作を示します。
操作
例
並び替え種別を取得する GET /lookup/sorttypes
言語を取得する
GET /lookup/languages
タイムゾーンを取得する GET /lookup/timezones
検索条件種別を取得する GET /lookup/filtertypes
カウント種別を取得する GET /lookup/counttypes
ユーザを取得する
GET /lookup/users
タグを取得する
GET /lookup/tags
高度な検索条件種別を取 GET /lookup/advancedfiltertypes
得する
地域を取得する
GET /lookup/regions
プロジェクトを取得する GET /lookup/projects
インフルエンサー総計値 GET /lookup/influencermetrics
を取得する
外部取引先種別を取得す GET /lookup/externalaccounttypes
る
拡張メディアタイプを取 GET /lookup/extendedmediatypes
得する
354
第 22 章 Radian6 API
操作
例
メディアグループタイプ GET /lookup/mediagroupproviders
を取得する
ワークフローを取得する GET /lookup/workflow
auth_token および auth_appkey ヘッダーパラメータはすべてのコールに必須で
す。各操作についての詳細は、Radian6 API ドキュメントのLookup サービスのリファレ
ンスを参照してください。
リソース
Radian6 API に関する詳細な情報を取得するには、次のリソースを参照してください。
• Radian6 API ドキュメント: http://socialcloud.radian6.com/docs
• Radian6 の使用開始:
http://www.salesforcemarketingcloud.com/products/social-media-listening/
• Radian6 の事例:
http://www.salesforcemarketingcloud.com/resources/videos/
355
第 23 章
Pardot API
Pardot を使用すると、オンラインマーケティングキャンペーンを効率的に作成、リリー
ス、管理できます。Pardot REST API では、Pardot の見込み客、訪問者、活動、商談、お
よび他のデータにアプリケーションからアクセスできます。
すべての Pardot アカウントとユーザロールは、API にフルアクセスできます。コネクタ
を使用すると、Pardot と Salesforce の統合と同期が自動的に行われます。コネクタでサ
ポートされないサードパーティのツールやサービスが関係するカスタムインテグレー
ションを実行している場合は、Pardot API を使用できます。
要求を発行する前に、API で認証する必要があります。すべての要求では、HTTP GET
または POST を使用する必要があります。SSL の使用により GET 要求は安全ですが、
注意を要するか長いパラメータ値が POST メッセージ本文に含まれている場合は、
POST の使用をお勧めします。
update 要求を実行する場合、要求で指定された項目のみが更新され、他の項目は変
更されません。update 時に必須項目がクリアされると、要求は却下されます。
API で使用できるオブジェクトは、Pardot ユーザインターフェース内のオブジェクトに
対応します。これらのオブジェクトには、商談、見込み客、ユーザ、訪問者などが含
まれることがあります。
サポートされるブラウザ
Pardot では、次のブラウザをサポートしています。
• Mozilla® Firefox®
• Google Chrome™
• Microsoft® Internet Explorer®
• Apple® Safari®
「outdated browse (古いブラウザ)」という警告が表示された場合は、上記のブラウザの
最新バージョンにアップグレードしてください。
357
第 23 章 Pardot API
サポート対象の Salesforce のエディション
Pardot では、次の Salesforce エディションをサポートしています。
• Professional Edition
• Enterprise Edition
• Unlimited Edition
既存のSalesforceのお客様が上記のいずれかのエディションにアップグレードする場合
は、担当者にご連絡ください。
クイックスタート
Pardot API を使用すると、Pardot 内のデータにアプリケーションからアクセスできます。
Pardot API の使用を開始する手順は、次のとおりです。
1. API で認証します。
2. API を使用して要求を発行します。API 要求は、API コンソールからテストできま
す。
例: API キーの取得方法に関する詳細とデモや、見込み客をクエリおよび作成する
方法については、Pardot Developer サイトを参照してください。
ステップ 1: API で認証する
要求を発行する前に、API で認証する必要があります。
API への接続を正常に認証するには、次の前提条件を満たしている必要があります。
1. Pardot API に対するすべての要求は、SSL で暗号化された接続を介して行う必要
があります。
2. 認証要求では、HTTP POST を使用する必要があります。
3. API 要求を送信する Pardot ユーザアカウントの email、password、および
user_key を取得します ([私の設定] にあるアプリケーションで入手可能)。
以上の要件が満たされたら、API キーを取得します。ユーザキーと API キーは、どちら
も個々のユーザに固有です。API キーは、60 分間有効です。これに対し、ユーザキー
358
第 23 章 Pardot API
は無期限で有効です。認証を行うには、次の要求を発行します (italics で示される
値を、自分のアカウントの値で置き換えます)。
POST: https://pi.pardot.com/api/login/version/3
message body: email=email&password=password&user_key=user_key
パラメータ
説明
email
ユーザアカウントのメールアドレス
password
ユーザアカウントのパスワード
user_key
ユーザアカウントの、32 ビットで 16 進数
のユーザキー
すべてのパラメータは必須です。認証に成功すると、32 文字で 16 進数の API キーが次
の形式で返されます。
<rsp stat="ok" version="1.0">
<api_key>5a1698a233e73d7c8ccd60d775fbc68a</api_key>
</rsp>
認証に失敗すると、次の応答が返されます。
<rsp stat="fail" version="1.0">
<err code="15">Login failed</err>
</rsp>
以降の認証要求では、現在の有効な API キーが返されるか、以前のキーが期限切れの
場合は新しく生成された API キーが返されます。
359
第 23 章 Pardot API
ステップ 2: Pardot API を使用して要求を発行する
Pardot API は、Pardot ユーザインターフェースで使用できる多くのオブジェクトに対す
るさまざまな要求を処理します。
API へのほとんどの要求では、標準化された形式が使用されます。すべての要求では、
HTTP GET または POST を使用する必要があります。SSL の使用により GET 要求は安全
ですが、注意を要するか長いパラメータ値が POST メッセージ本文に含まれている場
合は、POST の使用をお勧めします。次のコンポーネントを使用して、要求を発行す
る必要があります。
POST:
https://pi.pardot.com/api/object/version/3/do/operator/identifier_field/identifier
message body:
api_key=your_api_key&user_key=your_user_key&parameters_for_request
GET:
https://pi.pardot.com/api/object/version/3/do/operator/identifier_field/identifier
?api_key=your_api_key&user_key=your_user_key&parameters_for_request
パラメータ
説明
object
API 要求から返されるオブジェクト種別
operator
指定されたオブジェクト種別で実行する
操作
identifier_field
指定されたオブジェクト種別の識別に使
用する項目
identifier
指定されたオブジェクトの識別子
your_api_key
認証時に取得された API キー
your_user_key
認証時に使用されたユーザキー
format
API データ形式。xml または json のいずれ
かになります (デフォルトは xml)。
360
第 23 章 Pardot API
パラメータ
説明
parameters_for_request
要求に固有のパラメータ
format と parameters_for_request を除き、すべてのパラメータは必須です。
パラメータの順序は任意です。パラメータは従来の HTML パラメータ構文を使用して
渡され、'?' はパラメータ文字列の開始を示し (GET 要求の場合のみ)、'&' はパラメー
タ間の区切り文字として使用されます。API から返されるデータは、UTF-8 文字コード
を使用する JSON または XML 1.0 で書式設定されます。応答に含まれる一部の文字は
HTML エンティティとして符号化されることがあり、その場合はクライアント側で復
号化が必要です。また、API 要求で指定されるすべてのパラメータは、URL 符号化して
から送信する必要があります。
API では通常、現在のバージョンの対象オブジェクトデータを含む XML または JSON が
返されます。ただし、要求に失敗すると、エラーコードとメッセージを含む簡単な応
答が返されます。
オブジェクトのクエリ
特に明記されていない限り、検索条件は任意の組み合わせか順序、またはその両方で
使用できます。output=mobile が指定されていないと、各クエリ要求から 200 件の
結果が返されます。この制限は、モバイルデバイス用に書式設定された応答には適用
されません。GET 要求には URL 文字制限があるため、カンマ区切りの ID など、パラメー
タ値が長くなる場合は POST 要求の使用をお勧めします。オブジェクトをクエリする
場合は、結果セット間の移動、残りの結果の取得、および並び替えを行うパラメータ
を含めることができます。
API 応答形式の変更
Pardot API では、XML または JSON 応答で異なる詳細レベルを返す出力形式をいくつかサ
ポートしています。出力形式を定義するには、output 要求パラメータを指定します。
次のような出力形式がサポートされています。
• full — Pardot オブジェクトでサポートされるすべてのデータと、関連するすべて
のオブジェクトを返します。
361
第 23 章 Pardot API
• simple — Pardot オブジェクトのデータでサポートされるすべてのデータを返しま
す。
• mobile — オブジェクトデータの短縮バージョンを返します。この出力形式は、
モバイルアプリケーションに適しています。
出力要求パラメータが定義されていない場合、出力形式はデフォルトの full に設定
されます
XML 応答形式のサンプル
次の例に、opportunity の XML 応答形式を示します。
output=full の場合:
<rsp stat="ok" version="1.0">
<opportunity>
...
<campaign>
...
</campaign>
<prospects>
<prospect>
...
</prospect>
</prospects>
<opportunity_activities>
<visitor_activity>
...
</visitor_activity>
362
第 23 章 Pardot API
</opportunity_activities>
</opportunity>
</rsp>
output=simple の場合:
<rsp stat="ok" version="1.0">
<opportunity>
...
<campaign>
...
</campaign>
<prospects>
<prospect>
...
</prospect>
</prospects>
</opportunity>
</rsp>
output=mobile の場合:
<rsp stat="ok" version="1.0">
<opportunity>
...
363
第 23 章 Pardot API
</opportunity>
</rsp>
API の使用
API から返される各項目は、Pardot ユーザインターフェース内の項目に対応付けられま
す。個々のレコード (見込み客およびリード/取引先責任者) と取引先の項目の対応付け
は、コネクタの検証時に自動的に設定されます。
デフォルトでは、Pardot 独自の項目 (score、grade、Pardot campaign など)、紹介者項目、
AppExchange パッケージのインストール時に作成された Google Analytics 項目などを除き、
Salesforce はすべての項目のマスタとなります。
ここでは、リード、取引先責任者、取引先、商談項目のみを同期します。ただし、他
のほどんどの項目には Pardot をマスタにし、必要に応じてデフォルトのほとんどの対
応付けを変更してもかまいません。
項目の対応付けの詳細は、次のリソースを参照してください。
• Getting Started with the Salesforce Integration
• Opportunities in Pardot
• Default Prospect and Account Field Mapping
API から返すことができるか更新できる項目についての詳細は、Pardot API ドキュメン
トのオブジェクト項目のリファレンスを参照してください。
prospect の使用
見込み客へのアクセスと管理を行います。
サポートされている操作
prospect でサポートされている操作は、assign、unassign、create、read、update、
upsert、delete、query です。
364
第 23 章 Pardot API
操作
説明
assign
表示形式
/api/prospect/version/3/do/assign/email/email?...
必須パラメータ
user_key、api_key、email (user_email または
user_id または group_id)
説明
email で指定された見込み客を、指定された Pardot ユー
ザ/グループに割り当てまたは再割り当てします。対象
ユーザ/グループを識別するには、user_email、
user_id、または group_id のいずれか 1 つのパラメー
タを指定する必要があります。見込み客の更新バージョ
ンを返します。
assign
表示形式
/api/prospect/version/3/do/assign/id/id?...
必須パラメータ
user_key、api_key、id (user_email または
user_id または group_id)
説明
id で指定された見込み客を、指定された Pardot ユーザ/
グループに割り当てまたは再割り当てします。対象ユー
ザ/グループを識別するには、user_email、user_id、
または group_id のいずれか 1 つのパラメータを指定す
る必要があります。見込み客の更新バージョンを返しま
す。
create
表示形式
/api/prospect/version/3/do/create/email/email?...
必須パラメータ
user_key、api_key、email
365
第 23 章 Pardot API
操作
説明
説明
指定されたデータを使用して、新しい見込み客を作成し
ます。email には、一意のメールアドレスを指定する必
要があります。この要求に、メールリスト登録およびカ
スタム項目データを追加することもできます。
query
表示形式
/api/prospect/version/3/do/query?...
必須パラメータ
user_key、api_key
説明
指定された条件パラメータと一致する見込み客を返しま
す。
query
表示形式
/api/opportunity/version/3/do/query?...
必須パラメータ
user_key、api_key
説明
指定された条件パラメータと一致する商談を返します。
見込み客の割り当てと再割り当て
見込み客の割り当てまたは再割り当てを行うには、割り当てる見込み客と、割り当て
の対象ユーザ/グループの両方を定義する必要があります。見込み客は、その Pardot ID
またはメールアドレスで指定できます。ユーザまたはグループは、その Pardot ユーザ
ID、メールアドレス、または Pardot グループ ID で指定できます。
366
第 23 章 Pardot API
次の例に、パラメータの可能な組み合わせを示します。[斜体]で示されるパラメータ
を、特定の値に置き換える必要があります。
/api/prospect/version/3/do/assign/email/?user_email=user_email
&api_key=api_key&user_key=user_key
/api/prospect/version/3/do/assign/email/?user_id=user_id
&api_key=api_key&user_key=user_key
/api/prospect/version/3/do/assign/email/?group_id=group_id
&api_key=api_key&user_key=user_key
/api/prospect/version/3/do/assign/id/?user_email=user_email
&api_key=api_key&user_key=user_key
/api/prospect/version/3/do/assign/id/?user_id=user_id
&api_key=api_key&user_key=user_key
/api/prospect/version/3/do/assign/id/?group_id=group_id
&api_key=api_key&user_key=user_key
要求で特に指示された値のみが更新されます。他のすべての値は変更されません。値
をクリアするには、status= のように、指定値のないパラメータを含む update 要
求を送信します。
見込み客の作成
API を使用して見込み客を作成する場合は、有効かつ一意のメールアドレスのみが必
要です。create 要求で、他の見込み客項目の値を指定することもできます。開発者
は、italics で示されるパラメータを特定の値に置き換える必要があります。
次の例に、新しい見込み客を作成する方法を示します。
/api/prospect/version/3/do/create/email/[email protected]?first_name=first_name
&last_name=last_name&api_key=api_key&user_key=user_key
367
第 23 章 Pardot API
prospect についての詳細は、Pardot API ドキュメントの「prospect の使用」および見込み
客項目のリファレンスを参照してください。
項目値の更新
見込み客データ項目の値を変更するには、更新する項目ごとにパラメータを指定して
update 要求を送信します。各パラメータの形式は field_name=value です。カス
タム項目値の更新にも、同じ構文が使用されます。
次の例に、メールアドレスが [email protected] の見込み客の電話番号を更新する方
法を示します。
/api/prospect/version/3/do/update/email/[email protected]?phone=888-123-4567
&api_key=api_key&user_key=user_key
要求で特に指示された値のみが更新されます。他のすべての値は変更されません。値
をクリアするには、phone= のように、指定値のないパラメータを含む update 要求
を送信します。
メモ: 複数の応答を記録するよう設定された項目の場合、この方法では値をクリ
アできません。
opportunity の使用
商談へのアクセスと管理を行います。
サポートされている操作
opportunity でサポートされている操作は、create、read、update、delete、
undelete、query です。
操作
説明
create
表示形式
/api/opportunity/version/3/do/create/
prospect_email/prospect_email?...
368
第 23 章 Pardot API
操作
説明
必須パラメータ
user_key、api_key、prospect_email、name、
value、probability
説明
指定されたデータを使用して、新しい商談を作成します。
prospect_email パラメータは、既存の見込み客に対応
している必要があります。name、value、probability
も指定する必要があります。
メモ: prospect_email と prospect_id の両方が指
定されている場合は、どちらも同じ見込み客に対応し
ている必要があります。
create
表示形式
/api/opportunity/version/3/do/create/
prospect_id/prospect_id?...
必須パラメータ
user_key、api_key、prospect_email、name、
value、probability
説明
指定されたデータを使用して、新しい商談を作成します。
prospect_id パラメータは、既存の見込み客に対応し
ている必要があります。name、value、probability
も指定する必要があります。
update
表示形式
/api/opportunity/version/3/do/update/id/id?...
必須パラメータ
user_key、api_key、id
369
第 23 章 Pardot API
操作
説明
説明
id (対象商談の Pardot ID) で指定された商談に提供される
データを更新します。要求によって更新されない項目は
変更されません。商談の更新バージョンを返します。
query
表示形式
/api/opportunity/version/3/do/query?...
必須パラメータ
user_key、api_key
説明
指定された条件パラメータと一致する商談を返します。
使用方法
商談データ項目の値を変更するには、更新する項目ごとにパラメータを指定して
update 要求を送信します。各パラメータの形式は field_name=value です。
次の例では、Pardot ID が 27 の商談の値を更新します。
POST: /api/opportunity/version/3/do/update/id/27 message body:
value=50000&api_key=api_key&user_key=user_key
要求で特に指示された値のみが更新されます。他のすべての値は変更されません。値
をクリアするには、status= のように、指定値のないパラメータを含む update 要
求を送信します。
opportunity についての詳細は、Pardot API ドキュメントの「opportunity の使用」および商
談項目のリファレンスを参照してください。
visitor の使用
訪問者へのアクセスとクエリを行います。
370
第 23 章 Pardot API
サポートされている操作
visitor でサポートされている操作は、assign、read、query です。
操作
説明
assign
表示形式
/api/visitor/version/3/do/assign/id/id?...
必須パラメータ
user_key、api_key、id (prospect_email または
prospect_id)
説明
id で指定された訪問者を、指定された見込み客に割り当
てまたは再割り当てします。対象見込み客を識別するに
は、prospect_email または prospect_id のいずれか
1 つのパラメータを指定する必要があります。訪問者の
更新バージョンを返します。
read
表示形式
/api/visitor/version/3/do/read/id/id?...
必須パラメータ
user_key、api_key、id
説明
関連する訪問者アクティビティ、特定された会社データ、
訪問者の紹介者など、id で指定された訪問者のデータを
返します。id パラメータは、対象訪問者の Pardot ID で
す。
query
表示形式
/api/visitor/version/3/do/query?...
必須パラメータ
user_key、api_key
371
第 23 章 Pardot API
操作
説明
説明
指定された条件パラメータと一致する訪問者を返します。
訪問者の割り当てと再割り当て
訪問者の割り当てまたは再割り当てを行うには、割り当てる訪問者と、割り当ての対
象見込み客の両方を定義する必要があります。訪問者は、その Pardot ID で指定されま
す。見込み客は、その Pardot ID またはメールアドレスで指定できます。
次の例に、パラメータの可能な組み合わせを示します。[斜体]で示されるパラメータ
を、特定の値に置き換える必要があります。
/api/visitor/version/3/do/assign/id/visitor_id?prospect_email=prospect_email
&api_key=api_key&user_key=user_key
/api/visitor/version/3/do/assign/id/visitor_id?prospect_id=prospect_id
&api_key=api_key&user_key=user_key
visitor についての詳細は、Pardot API ドキュメントの「visitor の使用」および訪問者項目
のリファレンスを参照してください。
visitorActivity の使用
訪問者アクティビティの参照とクエリを行います。
サポートされている操作
visitorActivity でサポートされている操作は、read と query です。次の例に、訪問者を
参照およびクエリする方法を示します。
372
第 23 章 Pardot API
操作
説明
read
表示形式
/api/visitorActivity/version/3/do/read/id/id?...
必須パラメータ
user_key、api_key、id
説明
id (対象訪問者アクティビティの Pardot ID) で指定された
訪問者アクティビティのデータを返します。
query
表示形式
/api/visitorActivity/version/3/do/query?...
必須パラメータ
user_key、api_key、search_criteria、
result_set_criteria
説明
指定された条件パラメータと一致する訪問者アクティビ
ティを返します。
使用方法
visitorActivity についての詳細は、Pardot API ドキュメントの「visitorActivity の使用」および
訪問者アクティビティ項目のリファレンスを参照してください。
user の使用
ユーザの参照とクエリを行います。
サポートされている操作
user でサポートされている操作は、read と query です。次の例に、ユーザを割り当
て、参照およびクエリする方法を示します。
373
第 23 章 Pardot API
操作
説明
read
表示形式
/api/user/version/3/do/read/email/email?...
必須パラメータ
user_key、api_key、id
説明
email (対象ユーザのメールアドレス) で指定されたユー
ザのデータを返します。
read
表示形式
/api/user/version/3/do/read/id/id?...
必須パラメータ
user_key、api_key、id
説明
id (対象ユーザの Pardot ID) で指定されたユーザのデータ
を返します。
query
表示形式
/api/user/version/3/do/query?...
必須パラメータ
user_key、api_key
説明
指定された条件パラメータと一致するユーザを返します。
使用方法
user についての詳細は、Pardot API ドキュメントの「user の使用」およびユーザ項目の
リファレンスを参照してください。
374
第 23 章 Pardot API
visit の使用
ユーザ訪問の参照とクエリを行います。
サポートされている操作
visit でサポートされている操作は、read と query です。次の例に、訪問を参照およ
びクエリする方法を示します。
操作
説明
read
表示形式
/api/visit/version/3/do/read/id/id?...
必須パラメータ
user_key、api_key、id
説明
関連する訪問者ページビューなど、id で指定された訪問
のデータを返します。id パラメータは、対象訪問の Pardot
ID です。
query
表示形式
/api/visit/version/3/do/query?...
必須パラメータ
user_key、api_key、(ids、visitor_ids、
prospect_ids)
説明
指定された条件パラメータと一致する訪問を返します。
使用方法
visit についての詳細は、Pardot API ドキュメントの「visit の使用」および訪問項目のリ
ファレンスを参照してください。
375
第 23 章 Pardot API
list の使用
メールリスト登録の参照とクエリを行います。
サポートされている操作
list でサポートされている操作は、read と query です。次の例に、リストを参照お
よびクエリする方法を示します。
操作
説明
read
表示形式
/api/list/version/3/do/read/id/id?...
必須パラメータ
user_key、api_key、id
説明
id (対象リストの Pardot ID) で指定されたリストのデータ
を返します。
query
表示形式
/api/list/version/3/do/query?...
必須パラメータ
user_key、api_key
説明
指定された条件パラメータと一致するリストを返します。
使用方法
list についての詳細は、Pardot API ドキュメントの「list の使用」およびリスト項目のリ
ファレンスを参照してください。
376
第 23 章 Pardot API
prospectAccount の使用
見込み客取引先へのアクセスと管理を行います。
サポートされている操作
prospectAccount でサポートされている操作は、create、describe、read、update、
query です。次の例に、見込み客取引先を作成、参照、クエリする方法を示します。
操作
説明
create
表示形式
/api/prospectAccount/version/3/do/create?...
必須パラメータ
api_key、user_key
説明
新しい見込み客取引先を作成します。
read
表示形式
/api/prospectAccount/version/3/do/read/id/id?...
必須パラメータ
user_key、api_key、id
説明
id (対象見込み客取引先の Pardot ID) で指定された見込み
客取引先のデータを返します。
query
表示形式
/api/prospectAccount/version/3/do/query?...
必須パラメータ
user_key、api_key
377
第 23 章 Pardot API
操作
説明
説明
指定された条件パラメータと一致する見込み客取引先を
返します。
使用方法
prospectAccount についての詳細は、Pardot API ドキュメントの「prospectAccount の使用」
および見込み客取引先項目のリファレンスを参照してください。
メールの読み取り
Pardot ID に基づいてメールを読み取ります。
サポートされている操作
次の例に、メールを読み取る方法を示します。
操作
説明
read
表示形式
/api/email/version/3/do/read/id/email_id?...
必須パラメータ
user_key、api_key、email
説明
id (対象メールの Pardot ID) で指定されたメールのデータ
を返します。
使用方法
詳細は、Pardot API ドキュメントのメール項目のリファレンスを参照してください。
378
第 23 章 Pardot API
1 対 1 メールの送信
1 人の見込み客に 1 通のメールを送信します。
サポートされている操作
次の例に、見込み客に 1 対 1 メールを送信する方法を示します。
操作
説明
send
表示形式
/api/email/version/3/do/send/prospect_id
/<prospect_id>?...
必須パラメータ
user_key、api_key、campaign_id、
(email_template_id または (text_content、name、
および subject))、(from_email または
from_user_id)
説明
<prospect_id> で識別される見込み客に 1 対 1 メールを
送信します。
send
表示形式
/api/email/version/3/do/send/prospect_email
/<prospect_email>?...
必須パラメータ
user_key、api_key、campaign_id、
(email_template_id または (text_content、name、
および subject))、(from_email または
from_user_id)
説明
<prospect_email> で識別される見込み客に 1 対 1 メー
ルを送信します。
379
第 23 章 Pardot API
使用方法
詳細は、Pardot API ドキュメントのメール項目のリファレンスを参照してください。
リストメールの送信
予定された日時に見込み客にメールを送信します。
サポートされている操作
次の例に、見込み客にメールを送信する方法を示します。
操作
説明
send
表示形式
/api/email/version/3/do/send
必須パラメータ
user_key、api_key、list_ids[]、campaign_id、
(email_template または (text_content、name、お
よび subject))、(from_email または from_user_id)
説明
list_ids[] で識別されるリストのすべての見込み客に
メールを送信します。
使用方法
詳細は、Pardot API ドキュメントのメール項目のリファレンスを参照してください。
リソース
Pardot API についての詳細は、次のリソースを使用してください。
• Pardot API and Technical Documentation: http://developer.pardot.com/
• Object Field References:
http://developer.pardot.com/kb/api-version-3/object-field-references
380
第 23 章 Pardot API
• Getting Started with the Salesforce Integration:
http://www.pardot.com/faqs/salesforce/getting-started-salesforce-com/
381
Service Cloud
第 24 章
Desk.com API
Desk.com では、顧客やコンテンツの管理からビジネスプロセスの自動化および洞察ま
で、効率的なオールインワンカスタマーサービスを実現できます。
Desk.com API では、Desk.com データを操作するための強力で単純な RESTful インターフェー
スを提供します。Desk.com API では、次のことができます。
• すべてのケースを参照する
• 顧客を名前で検索する
• 新しい会社を作成する
• 記事翻訳を更新する
• トピックを削除する
Desk.com API には、100 を超えるエンドポイントがあり、リッチなインテグレーション
およびアプリケーションを構築できます。
サポートされるブラウザ
Desk.com では、次のブラウザがサポートされます。
• Mozilla® Firefox®
• Google Chrome™
• Microsoft® Internet Explorer®
• Apple® Safari®
上記のブラウザの最新バージョンを使用することをお勧めします。Cookie と JavaScript
が有効になっている必要があります。
サポート対象の Salesforce のエディション
Desk.com では、次の Salesforce エディションと双方向に緊密に統合できます。
• Developer Edition
383
第 24 章 Desk.com API
• Group Edition
• Professional Edition
• Enterprise Edition
• Unlimited Edition
既存のSalesforceのお客様が上記のいずれかのエディションにアップグレードする場合
は、担当者にご連絡ください。
クイックスタート
Desk.com API は、HTTPS を介して JSON 形式で要求を処理します。
各リソースは、Desk.com 内のケース、顧客、または会社などのオブジェクトの状態や、
他のリソースとのリレーションを表します。各リソースは、名前付きの URI で識別さ
れ、HTTP メソッド (GET、POST、PATCH、DELETE など) を使用してアクセスされます。状
態はサーバに保存されないため、サーバに対して実行する各要求には、要求を処理す
るのに必要なすべての情報が含まれている必要があります。
PATCH は、リソースを変更するために使用されます。HTTP クライアントで PATCH/DELETE
要求を実行できない場合、X-HTTP-Method-Override ヘッダーを使用して POST 要求
を実行し、PATCH または DELETE を指定できます。
$ curl https://yoursite.desk.com/api/v2/cases/1 \
-u email:password \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-HTTP-Method-Override: PATCH' \
-X POST \
-d '{ "subject":"Updated" }'
各リソースで要求できるアクションは、ロールに基づいています。これらのロール
は、エージェント、レポートエージェント、ワークフローマネージャ、知識ベースマ
ネージャ、コンテンツマネージャ、ビジネスマネージャ、管理マネージャ、システム
384
第 24 章 Desk.com API
管理者、知識ベース管理者、請求管理者です。これらのロールおよびその権限につい
ての詳細は、「認証」を参照してください。
Desk.com API を開始する手順は、次のとおりです。
1. API で認証します。
2. データを要求します。
ステップ 1: API で認証する
データを送受信する前に、API で認証する必要があります。
API では SSL/TLS 経由の基本認証と OAuth 1.0a 認証の両方がサポートされます。自分自身
のアカウントのデータへのアクセスのみが必要な場合は、Desk.com のメールとパスワー
ドによる基本認証を使用します。
$ curl https://yoursite.desk.com/api/v2/cases \
-u email:password \
-H 'Accept: application/json'
ユーザに代わって他のアカウントにアクセスする必要がある API アプリケーションを
作成する場合は、OAuth 1.0a によって、ユーザのメールおよびパスワードを保管せずに
その API を使用できます。
API コールを実行する前に、登録された Desk.com ユーザが最初に OAuth 認証ワークフ
ローを実行し、クライアントアプリケーションがユーザの代わりに Desk.com にアクセ
スできるようにする必要があります。このプロセスの間、ユーザは Desk.com にログイ
ンしていて、アクセスを「許可」する必要があります。追加のセキュリティレイヤと
して、サイト管理者がアプリケーションを承認してからそのサイトのユーザが承認す
る必要があります。その後、ユーザはクライアントアプリケーション用に設定された
コールバック URL に、認証コードと共にリダイレクトされます。アプリケーションが
このコードを使用して、後続の API コールのための「アクセストークン」を取得でき
ます。
表 1 : OAuth エンドポイント
種別
エンドポイント
承認
/oauth/authorize
385
第 24 章 Desk.com API
種別
エンドポイント
要求トークン
/oauth/request_token
アクセストーク /oauth/access_token
ン
トークンは、[管理] > [設定] > [API] のクライアントアプリケーションの詳細の下にあり
ます。コンシューマ鍵、秘密、アクセストークン、アクセストークンの秘密の組み合
わせによって、API 要求を実行するために必要なすべてが決まります。
次の例は、標準の Ruby OAuth ライブラリを使用して API で認証する方法を示します。
require 'rubygems'
require 'oauth'
# KEY and SECRET are available in Desk.com Admin -> Settings -> API
->
# My Applications -> Key and Secret fields
KEY
= "YOUR_OAUTH_KEY"
SECRET = "YOUR_OAUTH_SECRET"
SITE
= "https://yoursite.desk.com"
# Start the process by requesting a token
callback_url
= "https://example.com/oauth/callback"
consumer
= OAuth::Consumer.new(KEY, SECRET, site: SITE)
request_token = consumer.get_request_token(oauth_callback: callback_url)
386
第 24 章 Desk.com API
# For demonstration purposes, visit this URL in your web browser and
authorize
# the request. for a live application, redirect your user user to this
URL
puts request_token.authorize_url(oauth_callback: callback_url)
# After the application is authorized, Desk.com will send a request
to your
# callback_url with two parameters, oauth_token and oauth_verifier
oauth_token
= "oauth_token_param"
oauth_verifier = "oauth_verifier_param"
# Retrieve the access token
access_token = request_token.get_access_token(oauth_token: oauth_token,
oauth_verifier: oauth_verifier)
# Send a GET request to Desk.com
access_token.get("/api/v2/cases")
# From here, you can store the credentials to make requests in the
future
ステップ 2: データを要求する
Desk.com API で認証したら、データを要求します。
387
第 24 章 Desk.com API
このセクションでは、トピックおよびトピック翻訳の参照、作成、更新、削除方法を
示す Ruby のサンプルコードについて説明します。この目的は、基本的な API コールを
簡単に説明することです。実際のアプリケーションでは、さらに HTTP コールのエラー
処理を実装し、POST や PATCH などのコールによって生じる可能性のある検証の問題を
修正するようにユーザに求める必要があります。
次のコードでは、システムに次の項目がインストールされていることを前提としてい
ます。
• Ruby 1.9.3
• Ruby gem
• JSON gem バージョン 1.8.0
• httparty gem バージョン 0.11.0
require 'rubygems'
require 'json'
require 'httparty'
AUTH
= { basic_auth: { username: '[email protected]', password:
"password" } }
BASE_URI = "https://yoursite.desk.com"
# get a resource
def get(uri, opts = {})
opts = opts.merge(AUTH)
uri
= BASE_URI + uri
puts "getting #{uri}"
388
第 24 章 Desk.com API
response = HTTParty.get(uri, opts)
JSON.parse(response.body)
end
# patch a resource
def patch(uri, opts = {})
opts = opts.merge(AUTH)
uri
= BASE_URI + uri
puts "patching #{uri}"
HTTParty.patch(uri, opts)
end
# post a resource
def post(uri, opts = {})
opts = opts.merge(AUTH)
uri
= BASE_URI + uri
puts "posting #{uri}"
389
第 24 章 Desk.com API
HTTParty.post(uri, opts)
end
# delete a resource
def delete(uri, opts = {})
opts = opts.merge(AUTH)
uri
= BASE_URI + uri
puts "deleting #{uri}"
HTTParty.delete(uri, opts)
end
def get_topics
get("/api/v2/topics", { query: { per_page: 1 } } )
end
def get_topic_translations(topic)
get(topic["_links"]["translations"]["href"])
end
# get the first topic
390
第 24 章 Desk.com API
topics = get_topics
topic
= topics["_embedded"]["entries"].first
# get that topic's first translation
translations = get_topic_translations(topic)
translation
= translations["_embedded"]["entries"].first
puts "current translation name: #{translation['name']}"
# update the translation's name
patch(translation["_links"]["self"]["href"], { query: { name: "name
updated via API at #{Time.now.to_s}" } } )
# get the updated translation
translation = get(translation["_links"]["self"]["href"])
puts "new translation name: #{translation['name']}"
# create a new topic
topic_options = { name: "new topic via API", allow_questions: false,
in_support_center: false }
post("/api/v2/topics", { query: topic_options } )
391
第 24 章 Desk.com API
# find the last topic
topics = get_topics
topics = get(topics["_links"]["last"]["href"])
topic
= topics["_embedded"]["entries"].last
puts "last topic's name: #{topic['name']}"
# delete the topic
response = delete(topic["_links"]["self"]["href"])
ベストプラクティス
Desk.com API は、RESTful アーキテクチャを使用します。このセクションでは、このアー
キテクチャといくつかのベストプラクティスについて説明します。
JSON インターフェース
要求と応答は JSON 形式です。
認証
HTTP 基本認証と OAuth 1.0a の両方がサポートされます。
承認
承認は、所定ユーザのロールに基づいて透過的に処理されます。
ステートレス
クライアントからサーバへの各要求には、要求を処理するのに必要な情報がすべ
て含まれている必要があります。サーバにはステート (状態) は保存されません。
キャッシュの動作
応答にはキャッシュ可能かどうかを示すラベルが HTTP ETag で付加されます。
392
第 24 章 Desk.com API
統一されたインターフェース
すべてのリソースには、HTTPS を介した汎用インターフェースを使用してアクセス
します。
名前付きリソース
すべてのリソースには、Desk.com URI に続くベース URI を使用して名前が付けられま
す。
階層化されたコンポーネント
Desk.com API v2 アーキテクチャでは、クライアントとサーバの間にプロキシサーバ
やゲートウェイなどを介在させることができます。
レート制限
レート制限は、認証方式に関係なく、ユーザ単位に実装されます。要求の現在のしき
い値は、1 分あたり 60 件に、サイトのフルタイムのエージェントとシステム管理者の
数を乗じた値で、1 分あたり最大 300 件になります。たとえば、システム管理者とエー
ジェントがそれぞれ 1 人のサイトでは、要求のレート制限は 1 分あたり 120 件になり
ます。要求は 1 分間の時間枠内で制限されます。
すべての応答には、レート制限に関する状況情報を持つヘッダーが含まれます。
X-Rate-Limit-Limit
エンドポイントへの 1 分あたりの最大要求数
X-Rate-Limit-Remaining
現在の時間枠で実行可能な残り要求数
X-Rate-Limit-Reset
次の時間枠が開始するまでの残り秒数
アプリケーションがレート制限に達すると、HTTP 429 エラー応答が次の本文と共に返
されます。
{
"message": "Too Many Requests"
}
393
第 24 章 Desk.com API
現在の時間枠で 40 秒が経過したとすると、システム管理者またはエージェントが 1 人
のサイトでは、次のヘッダーが返されます。
{
"X-Rate-Limit-Limit": 60,
"X-Rate-Limit-Remaining": 0,
"X-Rate-Limit-Reset": 20
}
制限に達すると、アプリケーションは X-Rate-Limit-Reset 秒が経過するまで要求
の実行を停止する必要があります。
要求の削減と帯域幅の節約
データを要求するとき、データと一緒に成功か失敗かを示す応答コードを受信しま
す。表示ラベル、グループ、マクロ、ユーザなどのリソースでも ETag キャッシュがサ
ポートされます。
下の応答例では、ヘッダーのみを示します。サーバのデータが変更された場合、レス
ポンスボディ全体と一緒に 200 が返されます。サーバのデータが変更されていない場
合、空のレスポンスボディと一緒に 304 が返され、アプリケーションのデータは最新
であることを示します。
次の例は、ETag なしの要求とその応答ヘッダー例を示します。
$ curl https://yoursite.desk.com/api/v2/groups \
-u email:password \
-I
HTTP/1.1 200 OK
Date: Fri, 24 May 2013 15:00:10 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
394
第 24 章 Desk.com API
X-Rate-Limit-Remaining: 59
X-Rate-Limit-Limit: 60
X-Rate-Limit-Reset: 50
X-AppVersion: 120.1
ETag: "1369407549"
X-Frame-Options: SAMEORIGIN
X-UA-Compatible: IE=Edge
Cache-Control: no-cache, private
X-Runtime: 0.323047
X-Rack-Cache: miss
次の例は、現在の ETag 付きの要求とその応答ヘッダー例を示します。
$ curl https://yoursite.desk.com/api/v2/groups \
-u email:password \
-H "if-none-match \"1369407549\""
-I
HTTP/1.1 304 Not Modified
Date: Fri, 24 May 2013 15:05:42 GMT
Connection: keep-alive
リソースの埋め込み
関連リソースは、HAL 仕様を使用してリンクされ、埋め込まれます。
リソースと 2 つ目のリソースとのリレーションが 1 対 1 または N 対 1 の場合、ほとん
どのリソースに 2 つ目のリソースを埋め込むことができます。アプリケーションが
ケースを読み込み、関連する顧客を取得する必要がある場合、単純な方法は、ケース
395
第 24 章 Desk.com API
を取得する要求を実行し、次に顧客を取得する別の要求を実行する方法です。ただ
し、顧客をケース内に埋め込めば、1 つの要求としてカウントされます。
次に、ケースを要求し、関連する顧客を埋め込む方法を、リソースが埋め込まれた応
答と共に示します。
$ curl https://yoursite.desk.com/api/v2/cases/1?embed=customer \
-u email:password \
-H 'Accept: application/json'
{
"subject": "Some case",
"_links": {
"self": {
"href": "/api/v2/cases/1",
"class": "case"
},
"customer": {
"href": "/api/v2/customers/1",
"class": "customer"
}
},
"_embedded": {
"customer": {
"first_name": "John",
"last_name": "Doe",
396
第 24 章 Desk.com API
"_links": {
"self": {
"href": "/api/v2/customers/1",
"class": "customer"
}
}
}
}
}
埋め込みは、特定のリソースまたはリソースのコレクションと関連するリソースをま
とめて取得する必要がある場合に役立ちます。埋め込めないリレーションもありま
す。また、埋め込みリレーションは、最上位のリソースまたはリソースのコレクショ
ンにのみ指定できます。
項目の選択
応答に含まれる項目は、要求にカンマ区切りの fields パラメータを指定することで
制限できます。_links はすべての応答で返されます。次の例は、項目選択を使用し
た要求を示します。
$ curl
https://yoursite.desk.com/api/v2/cases/:id\?fields\=subject,status \
-u email:password \
-H 'Accept: application/json'
ページネーションの調整
リソースのコレクションを要求すると、デフォルトで 50 個のリソースからなるページ
が 1 つ返されます。per_page パラメータを使用することで、ページあたり最大 100
397
第 24 章 Desk.com API
エントリを要求できます。デフォルトでは、page パラメータで指定しない限り最初の
ページが返されます。_links を使用して異なるページへのリンクをたどり、
_embedded エントリの下にある結果のリソースにアクセスできます。
curl https://yoursite.desk.com/api/v2/cases?per_page=100 \
-u email:password \
-H 'Accept: application/json'
詳細については、Desk.com API のドキュメントを参照してください。
API の使用
記事、ブランド、ケース、会社、顧客、およびその他の Desk.com データにアクセスし
て管理します。
このセクションでは、各リソースの一般的なアクションについて説明します。例の完
全なリストや応答の詳細は、Desk.com API のドキュメントを参照してください。
Articles
記事に対して、一覧表示、作成、更新などのアクションを実行します。
すべての記事のページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/articles
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/articles \
-u email:password \
-H 'Accept: application/json'
398
第 24 章 Desk.com API
応答の例
次の例では、本文の内容は簡略化されています。
{
"total_entries": 2,
"_links": {
"self": {
"href": "/api/v2/articles?page=1&per_page=30",
"class": "page"
},
"first": {
"href": "/api/v2/articles?page=1&per_page=30",
"class": "page"
},
"last": {
"href": "/api/v2/articles?page=1&per_page=30",
"class": "page"
},
"next": null,
"previous": null
},
"_embedded": {
"entries": [
399
第 24 章 Desk.com API
{
"subject": "Awesome Subject",
"body": "<p>Awesome apples</p>",
"internal_notes": "Notes to the agent here",
"publish_at": "2013-10-14T20:41:32Z",
"created_at": "2013-10-14T20:36:32Z",
"updated_at": "2013-10-14T20:41:32Z",
"_links": {
"self": {
"href": "/api/v2/articles/1",
"class": "article"
},
"topic": {
"href": "/api/v2/topics/1",
"class": "topic"
},
"translations": {
"href": "/api/v2/articles/1/translations",
"class": "article_translation"
}
}
},
400
第 24 章 Desk.com API
{
"subject": "How to make your customers happy",
"body": "<strong>Use Desk.com</strong>",
"body_email": "Email just doesn't cut it",
"internal_notes": "Notes to the agent here",
"publish_at": "2013-10-14T20:41:32Z",
"created_at": "2013-10-14T20:36:32Z",
"updated_at": "2013-10-14T20:41:32Z",
"_links": {
"self": {
"href": "/api/v2/articles/2",
"class": "article"
},
"topic": {
"href": "/api/v2/topics/1",
"class": "topic"
},
"translations": {
"href": "/api/v2/articles/2/translations",
"class": "article_translation"
}
}
401
第 24 章 Desk.com API
}
]
}
}
記事用のコール
次に、その他すべての記事用コールの一覧を示します。
アクション
1 つの記事を表示
する
記事を作成する
記事を更新する
記事を削除する
例
GET https://yoursite.desk.com/api/v2/articles/:id
POST https://yoursite.desk.com/api/v2/articles
PATCH https://yoursite.desk.com/api/v2/articles/:id
DELETE https://yoursite.desk.com/api/v2/articles/:id
公開記事全体を検
索する
GET https://yoursite.desk.com/api/v2/articles/search
記事翻訳を一覧表
示する
GET https://yoursite.desk.com/api/v2/articles/
:article_id/translations
1 つの記事翻訳を
表示する
GET https://yoursite.desk.com/api/v2/articles/
:article_id/translations/:locale
402
第 24 章 Desk.com API
アクション
記事翻訳を作成す
る
例
POST
https://yoursite.desk.com/api/v2/articles/
:article_id/translations
記事翻訳を更新す
る
PATCH https://yoursite.desk.com/api/v2/articles/
:article_id/translations/:locale
ロールや項目を含む、上記の各アクションについての詳細は、記事のリファレンスを
参照してください。
brands
すべてのブランドを一覧表示したり、個別にブランドを取得したりします。
すべてのブランドのページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/brands
単一のブランドを取得します。
GET https://yoursite.desk.com/api/v2/brands/:id
ブランドのすべての記事を取得します。
GET https://yoursite.desk.com/api/v2/brands/:id/articles
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/brands/:id \
-u email:password \
-H 'Accept: application/json'
403
第 24 章 Desk.com API
応答の例
次の例では、本文の内容は簡略化されています。
{
"name": "Desk.com",
"created_at": "2013-10-14T20:36:32Z",
"updated_at": "2013-10-14T20:36:32Z",
"_links": {
"self": {
"href": "/api/v2/brands/1",
"class": "brand"
}
}
}
ブランドの取得についての詳細は、ブランドのリファレンスを参照してください。
Cases
ケースに対して、一覧表示、作成、更新などのアクションを実行します。
すべてのケースのページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/cases
単一のケースを取得します。URL 符号化で e- に続けて外部 ID を使用できます (例:
e-case%405-300)。
GET
https://yoursite.desk.com/api/v2/cases/:id
404
第 24 章 Desk.com API
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/cases/1 \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"external_id": null,
"subject": "Welcome",
"priority": 5,
"locked_until": null,
"description": null,
"status": "new",
"type": "email",
"language": "en_us",
"created_at": "2013-10-14T20:36:32Z",
"updated_at": "2013-10-14T20:36:32Z",
"active_at": null,
"received_at": "2012-05-02T21:38:48Z",
"custom_fields": {
"level": "vip"
},
405
第 24 章 Desk.com API
"_links": {
"self": {
"href": "/api/v2/cases/1",
"class": "case"
},
"message": {
"href": "/api/v2/cases/1/message",
"class": "message"
},
"customer": {
"href": "/api/v2/customers/1",
"class": "customer"
},
"assigned_user": {
"href": "/api/v2/users/2",
"class": "user"
},
"assigned_group": {
"href": "/api/v2/groups/1",
"class": "group"
},
"locked_by": null
406
第 24 章 Desk.com API
}
}
ケース用のコール
次のリストに、ケース用の他のすべてのコールを示します。
ケースアクション
アクション
ケースを作成する
例
POST https://yoursite.desk.com/api/v2/customers
/:customer_id/cases
ケースを削除する
ケースを転送する
ケースを検索する
DELETE https://yoursite.desk.com/api/v2/cases/:id
POST
https://yoursite.desk.com/api/v2/cases/:id/forward
GET https://yoursite.desk.com/api/v2/cases
/search?name=John+Doe&status=open
ケースを更新する
PATCH https://yoursite.desk.com/api/v2/cases/:id
メッセージアクション
アクション
メッセージを削除
する
例
DELETE
https://yoursite.desk.com/api/v2/cases/:case_id/message
407
第 24 章 Desk.com API
アクション
メッセージを取得
する
例
GET https://yoursite.desk.com/api/v2/cases
/:case_id/message
メッセージを更新
する
PATCH
https://yoursite.desk.com/api/v2/cases/:case_id/message
返信アクション
アクション
返信を作成する
すべての返信を一
覧表示する
例
POST
https://yoursite.desk.com/api/v2/cases/:case_id/replies/:id
GET https://yoursite.desk.com/api/v2/cases
/:case_id/replies
返信を取得する
GET https://yoursite.desk.com/api/v2/cases/
:case_id/replies/:id
返信を更新する
PATCH https://yoursite.desk.com/api/v2/cases
/:case_id/replies/:id
408
第 24 章 Desk.com API
メモアクション
アクション
メモを作成する
例
POST https://yoursite.desk.com/api/v2/cases
/:id/notes
メモを削除する
メモを一覧表示す
る
メモを取得する
DELETE
https://yoursite.desk.com/api/v2/cases/:case_id/notes/:id
GET
https://yoursite.desk.com/api/v2/cases/:case_id/notes
GET https://yoursite.desk.com/api/v2/cases
/:case_id/notes/:id
メモを更新する
PATCH
https://yoursite.desk.com/api/v2/cases/:case_id/notes/:id
添付アクション
アクション
ケースの添付ファ
イルを作成する
例
POST https://yoursite.desk.com/api/v2/cases/:id
/attachments
返信の添付ファイ
ルを作成する
POST https://yoursite.desk.com/api/v2/cases/:case_id
/replies/:reply_id/attachments
409
第 24 章 Desk.com API
アクション
すべてのケースの
添付ファイルを取
得する
すべてのメッセー
ジの添付ファイル
を取得する
すべての返信の添
付ファイルを取得
する
添付ファイルを取
得する
例
GET https://yoursite.desk.com/api/v2/cases/:case_id
/attachments
GET https://yoursite.desk.com/api/v2/cases/:case_id
/message/attachments
GET https://yoursite.desk.com/api/v2/cases/:case_id
/replies/:reply_id/attachments
GET https://yoursite.desk.com/api/v2/cases/:case_id
/attachments/:id
その他のケース用のコール
アクション
例
マクロをプレ
ビューする
POST
https://yoursite.desk.com/api/v2/cases/:case_id/macros/preview
ケース履歴を参照
する
GET
https://yoursite.desk.com/api/v2/cases/:case_id/history
すべてのケースリ
ンクを取得する
GET
https://yoursite.desk.com/api/v2/cases/:case_id/links
すべての表示ラベ
ルを取得する
GET
https://yoursite.desk.com/api/v2/cases/:case_id/labels
410
第 24 章 Desk.com API
ロールや項目を含む、上記の各アクションについての詳細は、ケースのリファレンス
を参照してください。
companies
会社に対して、一覧表示、作成、更新などのアクションを実行します。
すべての会社のページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/companies
単一の会社を取得します。
GET
https://yoursite.desk.com/api/v2/companies/:id
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/companies/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "Acme Inc",
"domains": [
"acmeinc.com",
"acmeinc.net"
],
"created_at": "2013-10-16T17:25:16Z",
"updated_at": "2013-10-16T17:25:16Z",
411
第 24 章 Desk.com API
"custom_fields": {
"employer_id": "123456789"
},
"_links": {
"self": {
"href": "/api/v2/companies/1",
"class": "company"
},
"customers": {
"href": "/api/v2/companies/1/customers",
"class": "customer"
}
}
}
会社用のコール
次のリストに、会社用の他のすべてのコールを示します。
アクション
会社を作成する
会社のすべての
ケースを取得する
例
POST https://yoursite.desk.com/api/v2/companies
GET
https://yoursite.desk.com/api/v2/companies/:company_id/cases
412
第 24 章 Desk.com API
アクション
検索
例
GET https://yoursite.desk.com/api/v2/companies
/search
会社を更新する
PATCH https://yoursite.desk.com/api/v2/companies/:id
ロールや項目を含む、上記の各アクションについての詳細は、会社のリファレンスを
参照してください。
Custom Fields
すべてのカスタム項目を一覧表示したり、個別にカスタム項目を取得したりします。
すべてのカスタム項目のページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/custom_fields
単一のブランドを取得します。
GET https://yoursite.desk.com/api/v2/brands/:id
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/custom_fields/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "frequent_buyer",
413
第 24 章 Desk.com API
"label": "Frequent Buyer",
"type": "customer",
"active": true,
"data": {
"type": "boolean"
},
"_links": {
"self": {
"href": "/api/v2/custom_fields/1",
"class": "custom_field"
}
}
}
カスタム項目の取得についての詳細は、カスタム項目のリファレンスを参照してくだ
さい。
customers
顧客データを一覧表示、作成、または更新します。
すべての顧客のページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/customers
単一の顧客を取得します。
GET
https://yoursite.desk.com/api/v2/customers/:id
414
第 24 章 Desk.com API
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/customers/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"first_name": "John",
"last_name": "Doe",
"company": "ACME, Inc",
"title": "Senior Ninja",
"external_id": null,
"background": "Great customer!",
"language": "en_us",
"locked_until": null,
"created_at": "2013-10-16T17:25:16Z",
"updated_at": "2013-10-16T17:25:16Z",
"custom_fields": {
"level": "vip"
},
"emails": [
{
415
第 24 章 Desk.com API
"type": "work",
"value": "[email protected]"
},
{
"type": "home",
"value": "[email protected]"
}
],
"phone_numbers": [
{
"type": "work",
"value": "123-456-7890"
}
],
"addresses": [
{
"type": "work",
"value": "123 Main St, San Francisco, CA 94105"
}
],
"_links": {
"self": {
416
第 24 章 Desk.com API
"href": "/api/v2/customers/1",
"class": "customer"
},
"cases": {
"href": "/api/v2/customers/1/cases",
"class": "case"
},
"locked_by": null
}
}
顧客用のコール
次のリストに、顧客用の他のすべてのコールを示します。
アクション
顧客を作成する
顧客を更新する
顧客を検索する
例
GET https://yoursite.desk.com/api/v2/customers
PATCH https://yoursite.desk.com/api/v2/customers/:id
GET https://yoursite.desk.com/api/v2/customers
/search
顧客のすべての
ケースを取得する
GET
https://yoursite.desk.com/api/v2/customers/:id/cases
417
第 24 章 Desk.com API
ロールや項目を含む、上記の各アクションについての詳細は、顧客のリファレンスを
参照してください。
ETags
さまざまなエンドポイントの ETag 値を一覧表示します。
GET https://yoursite.desk.com/api/v2/etags
Facebook accounts
すべての Facebook アカウントを一覧表示したり、個別に Facebook アカウントを取得し
たりします。
すべての Facebook アカウントのページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/facebook_accounts
単一の Facebook アカウントを取得します。
GET https://yoursite.desk.com/api/v2/facebook_accounts/:id
Facebook フィード
すべての Facebook フィードを一覧表示したり、個別に Facebook フィードを取得したり
します。
すべての Facebook フィードのページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/facebook_feeds
単一の Facebook フィードを取得します。
GET https://yoursite.desk.com/api/v2/facebook_feeds/:id
Facebook ユーザ
すべての Facebook ユーザを一覧表示したり、個別に Facebook ユーザを取得したりしま
す。
418
第 24 章 Desk.com API
すべての Facebook ユーザのページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/facebook_users
単一の Facebook ユーザを取得します。
GET https://yoursite.desk.com/api/v2/facebook_users/:id
filters
すべての検索条件を一覧表示したり、個別に検索条件を取得したり、特定の検索条件
のすべてのケースを取得したりします。
すべての検索条件のページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/filters
単一の検索条件を取得します。
GET https://yoursite.desk.com/api/v2/filters/:id
特定の検索条件のケースを取得します。
GET https://yoursite.desk.com/api/v2/filters/:id/cases
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/filters/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "My Active Cases",
"sort": "priority",
"sort_field": "priority",
419
第 24 章 Desk.com API
"sort_direction": "desc",
"position": 1,
"active": true,
"_links": {
"self": {
"href": "/api/v2/filters/1",
"class": "filter"
},
"group": null,
"user": null
}
}
検索条件の使用についての詳細は、検索条件のリファレンスを参照してください。
groups
グループに対して、一覧表示、作成、更新などのアクションを実行します。
すべてのグループのページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/groups
単一のグループを取得します。
GET
https://yoursite.desk.com/api/v2/groups/:id
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/groups/:id \
420
第 24 章 Desk.com API
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "Support Ninjas",
"_links": {
"self": {
"href": "/api/v2/groups/1",
"class": "group"
}
}
}
グループ用のコール
次のリストに、グループ用の他のすべてのコールを示します。
アクション
特定のグループの
すべての検索条件
を取得する
特定のグループの
すべての権限を取
得する
例
GET https://yoursite.desk.com/api/v2/groups/:id
/filters
GET
https://yoursite.desk.com/api/v2/groups/:id/permissions
421
第 24 章 Desk.com API
アクション
特定のグループの
すべてのユーザを
取得する
例
GET https://yoursite.desk.com/api/v2/groups/:id
/users
ロールや項目を含む、上記の各アクションについての詳細は、グループのリファレン
スを参照してください。
inbound mailboxes
すべての受信メールボックスを一覧表示したり、個別に受信メールボックスを取得し
たりします。
すべての受信メールボックスを一覧表示します。
GET https://yoursite.desk.com/api/v2/mailboxes/inbound
単一の受信メールボックスを取得します。
GET https://yoursite.desk.com/api/v2/mailboxes/inbound/:id
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/mailboxes/inbound/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "Support Mailbox",
"enabled": true,
422
第 24 章 Desk.com API
"type": "imaps",
"hostname": "mail.example.com",
"port": 993,
"email": "[email protected]",
"last_checked_at": "2013-10-16T17:25:16Z",
"created_at": "2013-10-16T17:25:16Z",
"updated_at": "2013-10-16T17:25:16Z",
"last_error": null,
"inbound_address_filter": null,
"outbound_address_filter": null,
"_links": {
"self": {
"href": "/api/v2/mailboxes/inbound/1",
"class": "inbound_mailbox"
},
"default_group": {
"href": "/api/v2/groups/1",
"class": "group"
},
"created_by": {
"href": "/api/v2/users/1",
"class": "user"
423
第 24 章 Desk.com API
},
"updated_by": {
"href": "/api/v2/users/1",
"class": "user"
}
}
}
メールボックスの取得についての詳細は、受信メールボックスのリファレンスを参照
してください。
insights
ビジネス洞察のメタデータを取得したり、ビジネス洞察のレポートを作成したりしま
す。
認証サイトの洞察メタデータを取得します。
GET https://yoursite.desk.com/api/v2/insights/meta
レポートを作成するには、次の要求を使用します。
POST https://yoursite.desk.com/api/v2/insights/reports
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/insights/reports \
-u email:password \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
424
第 24 章 Desk.com API
-d '{"resolution":"days", "min_date":"2013-06-01",
"max_date":"2013-07-30",
"dimension1_name":"*", "dimension1_values":"*",
"dimension2_name":"*", "dimension2_values":"*"}'
リクエストボディの例
{
"resolution": "days",
"min_date": "2012-06-01",
"max_date": "2013-07-30",
"dimension1_name": "*",
"dimension1_values": "*",
"dimension2_name": "*",
"dimension2_values": "*"
}
洞察の使用についての詳細は、Insights のリファレンスを参照してください。
integration URLs
インテグレーション URL に対して、一覧表示、作成、または更新などのアクションを
実行します。
すべてのインテグレーション URL のページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/integration_urls
単一のインテグレーション URL を取得します。
GET
https://yoursite.desk.com/api/v2/integration_urls/:id
425
第 24 章 Desk.com API
cURL 要求の例
$ curl
https://yoursite.desk.com/api/v2/integration_urls/:id\?customer_id\=1
\
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "Sample URL",
"description": "A sample Integration URL",
"enabled": true,
"markup": "http://www.example.com/name={{customer.name |
url_encode}}",
"rendered": "http://www.example.com/name=Andrew",
"created_at": "2013-10-16T17:25:16Z",
"updated_at": "2013-10-16T17:25:16Z",
"_links": {
"self": {
"href": "/api/v2/integration_urls/1",
"class": "integration_url"
}
}
}
426
第 24 章 Desk.com API
インテグレーション URL 用のコール
次のリストに、インテグレーション URL 用の他のすべてのコールを示します。
アクション
インテグレーショ
ン URL を作成する
例
POST https://yoursite.desk.com/api/v2
/integration_urls
インテグレーショ
ン URL を更新する
PATCH https://yoursite.desk.com/api/v2
/integration_urls/:id
インテグレーショ
ン URL を削除する
DELETE https://yoursite.desk.com/api/v2
/integration_urls/:id
ロールや項目を含む、上記の各アクションについての詳細は、インテグレーション
URL のリファレンスを参照してください。
jobs
ジョブを一覧表示、表示、または作成します。
すべてのジョブのページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/jobs
単一のジョブを取得するには、その id を要求に追加します。
GET https://yoursite.desk.com/api/v2/jobs/:id
バックグラウンドジョブを作成するには、次の要求を使用します。
POST https://yoursite.desk.com/api/v2/jobs
427
第 24 章 Desk.com API
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/jobs \
-u email:password \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"type": "bulk_case_update", "case": {"priority": 5, "_links":
{ "assigned_user": {"href": "/api/v2/users/1", "class": "user"}}},
"case_ids": [1,2,3]}'
リクエストボディの例
{
"type": "bulk_case_update",
"case": {
"priority": 5,
"_links": {
"assigned_user": {
"href": "/api/v2/users/1",
"class": "user"
}
}
},
"case_ids": [1,2,3]
428
第 24 章 Desk.com API
}
応答の例
{
"type": "bulk_case_update",
"status_message": "Completed",
"progress": 100,
"created_at": "2013-10-16T16:35:16Z",
"completed_at": "2013-10-16T17:25:16Z",
"_links": {
"self": {
"href": "/api/v2/jobs/1",
"class": "job"
},
"user": {
"href": "/api/v2/users/1",
"class": "user"
}
}
}
ジョブの使用についての詳細は、ジョブのリファレンスを参照してください。
429
第 24 章 Desk.com API
labels
表示ラベルに対して、一覧表示、作成、更新などのアクションを実行します。
すべての表示ラベルのページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/labels
単一の表示ラベルを取得します。
GET
https://yoursite.desk.com/api/v2/labels/:id
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/labels/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "MyLabel",
"description": "My Label Description",
"types": ["case","macro"],
"active": true,
"position": 1,
"_links": {
"self": {
"href": "/api/v2/labels/1",
"class": "label"
430
第 24 章 Desk.com API
}
}
}
表示ラベル用のコール
次のリストに、表示ラベル用の他のすべてのコールを示します。
アクション
例
表示ラベルを作成
する
POST https://yoursite.desk.com/api/v2/labels
表示ラベルを更新
する
PATCH https://yoursite.desk.com/api/v2/labels/:id
表示ラベルを削除
する
DELETE https://yoursite.desk.com/api/v2/labels/:id
ロールや項目を含む、上記の各アクションについての詳細は、表示ラベルのリファレ
ンスを参照してください。
macros
マクロに対して、一覧表示、作成、更新などのアクションを実行します。
すべてのマクロのページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/macros
単一のマクロを取得します。
GET
https://yoursite.desk.com/api/v2/macros/:id
431
第 24 章 Desk.com API
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/macros/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "Macro Macro",
"description": "On repeat",
"enabled": true,
"position": 1,
"folders": [
"Sample Macros",
"Favorites"
],
"_links": {
"self": {
"href": "/api/v2/macros/1",
"class": "macro"
},
"actions": {
"href": "/api/v2/macros/1/actions",
432
第 24 章 Desk.com API
"class": "macro_action"
}
}
}
マクロ用のコール
次のリストに、マクロ用の他のすべてのコールを示します。
アクション
マクロを作成する
マクロを更新する
マクロを削除する
マクロのすべての
アクションを取得
する
マクロのアクショ
ンを取得する
例
POST https://yoursite.desk.com/api/v2/macros
PATCH https://yoursite.desk.com/api/v2/macros/:id
DELETE https://yoursite.desk.com/api/v2/macros/:id
GET https://yoursite.desk.com/api/v2/macros/:macro_id
/actions
GET https://yoursite.desk.com/api/v2/macros/:macro_id
/actions/:id
マクロを更新する
PATCH
https://yoursite.desk.com/api/v2/macros/:macro_id
/actions/:id
ロールや項目を含む、上記の各アクションについての詳細は、マクロのリファレンス
を参照してください。
433
第 24 章 Desk.com API
Outbound Mailboxes
すべての送信メールボックスを一覧表示したり、個別に送信メールボックスを取得し
たりします。
すべての送信メールボックスのページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/outbound_mailboxes
単一の送信メールボックスを取得します。
GET https://yoursite.desk.com/api/v2/outbound_mailboxes/:id
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/outbound_mailboxes/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
次の例では、本文の内容は簡略化されています。
{
"from_name": "Support",
"from_email: "[email protected]",
"enabled": true,
"reply_to": "",
"hostname": "smtp.example.com",
"port": 587,
"last_error": null,
"type": "custom",
434
第 24 章 Desk.com API
"created_at": "2014-05-20T19:18:09Z",
"updated_at": "2014-05-20T19:18:09Z",
"_links": {
"self": {
"href": "/api/v2/mailboxes/outbound/1",
"class": "outbound_mailbox"
}
}
}
rules
すべてのルールを一覧表示したり、個別にルールを取得したりします。
すべてのルールのページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/rules
単一のルールを取得します。
GET https://yoursite.desk.com/api/v2/rules/:id
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/rules/:id \
-u email:password \
-H 'Accept: application/json'
435
第 24 章 Desk.com API
応答の例
次の例では、本文の内容は簡略化されています。
{
"name": "Assign to Support",
"description": "Assign inbound tweets to support group",
"enabled": true,
"created_at": "2013-10-16T17:25:16Z",
"updated_at": "2013-10-16T17:25:16Z",
"_links": {
"self": {
"href": "/api/v2/rules/1",
"class": "rule"
}
}
}
ルールの取得についての詳細は、ルールのリファレンスを参照してください。
site settings
すべてのサイト設定を一覧表示したり、個別にサイト設定を取得したりします。
すべてのサイト設定のページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/site_settings
単一のルールを取得します。
GET https://yoursite.desk.com/api/v2/site_settings/:id
436
第 24 章 Desk.com API
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/site_settings/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "company_name",
"value": "Cool Surfboard Co.",
"_links": {
"self": {
"href": "/api/v2/site_settings/1",
"class": "site_setting"
}
}
}
サイト設定の取得についての詳細は、Sites のリファレンスを参照してください。
system message
Desk.com では、システムメッセージリソースを使用して、次回のメンテナンスや、ユー
ザに影響する可能性のあるその他のニュースを通知します。これは、現在のシステム
メッセージ (存在する場合) を公開する参照のみのエンドポイントです。
すべてのシステムメッセージを取得します。
GET https://yoursite.desk.com/api/v2/system_message
437
第 24 章 Desk.com API
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/system_message \
-u email:password \
-X GET \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
応答の例
次の例では、本文の内容は簡略化されています。
{
"message": "We're not doing maintenance today, but if we were then
we would tell you about it here.",
"updated_at": "2013-10-16T17:25:16Z"
}
システムメッセージの取得についての詳細は、システムメッセージのリファレンスを
参照してください。
Topics
トピックに対して、一覧表示、作成、更新などのアクションを実行します。
すべてのトピックのページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/topics
単一のトピックを取得します。
GET
https://yoursite.desk.com/api/v2/topics/:id
438
第 24 章 Desk.com API
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/topics/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "Customer Support",
"description": "This is key to going from good to great",
"position": 1,
"allow_questions": true,
"in_support_center": true,
"created_at": "2013-10-06T17:35:16Z",
"updated_at": "2013-10-11T17:35:16Z",
"_links": {
"self": {
"href": "/api/v2/topics/1",
"class": "topic"
},
"articles": {
"href": "/api/v2/topics/1/articles",
"class": "article"
439
第 24 章 Desk.com API
},
"translations": {
"href": "/api/v2/topics/1/translations",
"class": "topic_translation"
}
}
}
トピック用のコール
次のリストに、トピック用の他のすべてのコールを示します。
アクション
例
トピックを作成す
る
POST https://yoursite.desk.com/api/v2/topics
トピックを更新す
る
PATCH https://yoursite.desk.com/api/v2/topics/:id
トピックを削除す
る
DELETE https://yoursite.desk.com/api/v2/topics/:id
トピックの翻訳を
取得する
GET https://yoursite.desk.com/api/v2/topics/:topic_id
/translations
単一のトピック翻
訳を取得する
GET https://yoursite.desk.com/api/v2/topics/:id
/translations/:locale
トピック翻訳を作
成する
POST
https://yoursite.desk.com/api/v2/topics/:topic_id
440
第 24 章 Desk.com API
アクション
例
/translations
トピック翻訳を更
新する
PATCH https://yoursite.desk.com/api/v2/topics/:id
/translations/:locale
トピック翻訳を削
除する
DELETE https://yoursite.desk.com/api/v2/topics/:id
/translations/:locale
ロールや項目を含む、上記の各アクションについての詳細は、Topics のリファレンス
を参照してください。
Twitter accounts
Twitter アカウントに対して、ツイートの一覧表示や作成などの)アクションを実行しま
す。
すべての Twitter アカウントのページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/twitter_accounts
単一の Twitter アカウントを取得します。
GET
https://yoursite.desk.com/api/v2/twitter_accounts/:id
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/twitter_accounts/:id \
-u email:password \
-H 'Accept: application/json'
441
第 24 章 Desk.com API
応答の例
{
"handle": "desk_dev",
"name": "Desk.com Development",
"profile_image": "http://www.example.com/image.png",
"active": true,
"created_at": "2013-04-16T17:35:16Z",
"updated_at": "2013-05-16T17:35:16Z",
"_links": {
"self": {
"href": "/api/v2/twitter_accounts/1",
"class": "twitter_account"
}
}
}
Twitter アカウント用のコール
次のリストに、Twitter アカウント用の他のすべてのコールを示します。
アクション
Twitter アカウント
からツイートを投
稿する
例
POST
https://yoursite.desk.com/api/v2/twitter_accounts
/:id/tweets
442
第 24 章 Desk.com API
アクション
例
Twitter アカウント
のすべてのツイー
トを取得する
ツイートを取得す
る
GET https://yoursite.desk.com/api/v2/twitter_accounts
/:id/tweets
GET https://yoursite.desk.com/api/v2/twitter_accounts
/:twitter_account_id/tweets/:id
ロールや項目を含む、上記の各アクションについての詳細は、Twitter アカウントのリ
ファレンスを参照してください。
Twitter ユーザ
Twitter ユーザを一覧表示、表示、または作成します。
Twitter ユーザのページ設定されたリストを取得します。
GET https://yoursite.desk.com/api/v2/twitter_users
単一の Twitter ユーザを取得します。
GET https://yoursite.desk.com/api/v2/twitter_users/:id
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/twitter_users/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
443
第 24 章 Desk.com API
"handle": "desk_dev",
"image_url": "http://example.com/image.png",
"followers_count": "123",
"verified": false,
"created_at": "2014-05-20T19:18:09Z",
"updated_at": "2014-05-20T19:18:09Z",
"_links": {
"self": {
"href": "/api/v2/twitter_users/1",
"class": "twitter_user"
},
"customer": {
"href": "/api/v2/customers/1",
"class": "customer"
}
}
}
詳細情報
Twitter ユーザの一覧表示、表示、および作成についての詳細は、
http://dev.desk.com/API/twitter-users/ を参照してください。
users
ユーザの取得やユーザ設定の取得などの他のアクションを実行します。
444
第 24 章 Desk.com API
すべてのユーザのページ設定されたリストを取得します。
GET
https://yoursite.desk.com/api/v2/users
単一のユーザを取得します。
GET
https://yoursite.desk.com/api/v2/users/:id
cURL 要求の例
$ curl https://yoursite.desk.com/api/v2/users/:id \
-u email:password \
-H 'Accept: application/json'
応答の例
{
"name": "John Doe",
"public_name": "John Doe",
"email": "[email protected]",
"level": "agent",
"_links": {
"self": {
"href": "/api/v2/users/1",
"class": "user"
},
"preferences": {
"href": "/api/v2/users/1/preferences",
445
第 24 章 Desk.com API
"class": "user_preference"
}
}
}
ユーザ用のコール
次のリストに、ユーザ用の他のすべてのコールを示します。
アクション
特定のユーザのす
べての設定を取得
する
ユーザ設定を取得
する
例
GET https://yoursite.desk.com/api/v2/users/:id
/preferences
GET https://yoursite.desk.com/api/v2/users/:id
/preferences/:id
ユーザ設定を更新
する
PATCH https://yoursite.desk.com/api/v2/users
/:user_id/preferences/:id
ロールや項目を含む、上記の各アクションについての詳細は、Users のリファレンスを
参照してください。
リソース
Desk.com API に関する詳細情報を取得するには、次のリソースを使用します。
• Desk.com API ドキュメント: http://dev.desk.com/API/using-the-api/
• Desk.com インテグレーションガイド: http://dev.desk.com/guides/
446
第 25 章
Live Agent API
Live Agent により、サービス組織は、Web ベースのテキストのみの Live Chat を使用して
顧客または Web サイトの訪問者とリアルタイムに接続できます。このガイドでは、リ
リース API および事前チャット API を使用して、チャットウィンドウと他の Live Agent
コンポーネントをカスタマイズする例をいくつか示します。
Live Agent API では、次のことができます。
• 開発 API を使用してリリースをカスタマイズする。
• 事前チャット API を使用して、顧客がエージェントとのチャットを開始する前に顧
客情報を収集する事前チャットフォームを作成する。
上記の API に加え、Visualforce のページやコンポーネントを使用して、顧客向けチャッ
トウィンドウの外観をカスタマイズしたり、チャット終了後に顧客に表示されるチャッ
ト後ページを作成したりできます。このガイドでは、Visualforceの使用については記載
していません。詳細は、『Live Agent 開発者ガイド』を参照してください。
また、Salesforce 設定を使用して、上記の操作および他の Live Agent コンポーネントをカ
スタマイズすることもできます。詳細は、Salesforce ヘルプの「Live Agent 実装のカスタ
マイズ」を参照してください。
447
第 25 章 Live Agent API
サポート対象の Salesforce のエディション
既存のSalesforceのお客様が上記のいずれかのエディショ
ンにアップグレードする場合は、担当者にご連絡くだ
さい。
前提条件
Live Agent をカスタマイズする前に、次のことを確認し
てください。
• 組織で Live Agent が有効になっている。
• システム管理者から Live Agent 機能ライセンスが付与
されている。機能ライセンスがなくても製品をカス
タマイズできますが、機能ライセンスがあるとカス
タマイズにアクセスし、テストすることができます。
エディション
Live Agent を使用可能な組
織: 2012 年 6 月 14 日より
も後に作成された
Performance Edition および
Developer Edition の組織
有料オプションで Live
Agent を使用可能なエディ
ション: Enterprise Edition
および Unlimited Edition
• Force.com サイトを作成し、チャットボタンおよびウィンドウの画像を静的リソー
スとしてアップロードした。Force.com サイトを使用せずに Live Agent をカスタマイ
ズする場合は、このステップを省略します。
API バージョン
Live Agent の API の異なるバージョンでは、使用できるメソッドとパラメータが異なり
ます。リリース API または事前チャット API を使用して開発を開始する前に、コードで
使用している API のバージョン番号が正しいことを確認します。
リリース API バージョン
リリース作成後に生成されたリリースコードから、組織で使用するリリース API のバー
ジョンを確認できます。
Summer '13 以前のリリースでは、バージョン 28.0 の開発 API をサポートしています。API
バージョン 28.0 の URL は、
https://hostname.salesforceliveagent.com/content/g/deployment.js の
ようになります。
448
第 25 章 Live Agent API
Winter '14 では、バージョン 29.0 の開発 API をサポートしています。API バージョン 29.0
の URL には、
https://hostname.salesforceliveagent.com/content/g/js/29.0/deployment.js
のようにバージョン番号が含まれます。
メモ: リリースで新しいメソッドとパラメータを使用するには、各 Web ページで
リリースコードを更新して、リリース API のバージョン 29.0 の URL を使用する必
要があります。
事前チャット情報 API バージョン
Winter '14 では、バージョン 29.0 の事前チャット API をサポートしています。API バー
ジョン 29.0 の URL には、
https://hostname.salesforceliveagent.com/content/g/js/29.0/prechat.js
のようにバージョン番号が含まれます。
リリース作成後に生成されたリリースコードから、組織のホスト名を確認できます。
リリースの作成
Web サイトで Live Agent をホストするリリースを作成します。各リリースには、訪問者
がサポートエージェントとチャットするために使用するチャットウィンドウが含まれ
ます。
リリースを作成したら、開発 API で会社のニーズに合わせてカスタマイズできます。
リリースを作成する手順は、次のとおりです。
1. [設定] で、[カスタマイズ] > [Live Agent] > [リリース] をクリックします。
2. [新規] をクリックします。
3. リリースの名前を入力します。このリリースの名前、つまりバージョンは自動
的に [API 参照名] になります。
4. チャットウィンドウのタイトルを入力します。
5. 訪問者がチャットセッションの終了時にコピーをダウンロードできるようにす
るには、[訪問者にトランスクリプトの保存を許可する] を選択します。
6. リリースに関連付けるサイトを選択します。
449
第 25 章 Live Agent API
7. [[チャット] ウィンドウのブランド画像] で、チャットウィンドウに表示される
画像を選択します。
8. [[モバイルチャット] ウィンドウのブランド画像] で、モバイルデバイスを使用
する訪問者のチャットウィンドウに表示される画像を選択します。
9. [保存] をクリックします。Salesforce は、リリースコードを生成します。
10. リリースコードをコピーして、Live Agent をリリースする各 Web ページに貼り付
けます。最高のパフォーマンスを得るには、このコードを body タグの直前に貼
り付けます。
例: リリースの作成についての詳細は、Salesforce オンラインヘルプの「Live Agent
リリースの作成」を参照してください。
リリース API を使用してリリースをカスタマイズ
する
リリースとは、Live Agent で有効化される会社の Web サイトの場所です。Live Agent リ
リース API を使用してリリースをカスタマイズできます。
リリースは、Web ページに追加する数行の JavaScript で構成されます。組織は、Live Agent
リリースを 1 つまたは複数持つことができます。たとえば、1 つのサービスセンター
で複数の Web サイトをサポートする場合、サイトごとに別々のリリースを作成する
と、訪問者に複数のチャットウィンドウを表示できます。各リリースには、訪問者が
サポートエージェントとチャットするために使用するチャットウィンドウが含まれま
す。
リリース API は、JavaScript ベースの API であり、リリースをカスタマイズしてバックエ
ンド機能を指定できます。
リリースの作成
Web サイトで Live Agent をホストするリリースを作成します。各リリースには、訪問者
がサポートエージェントとチャットするために使用するチャットウィンドウが含まれ
ます。
リリースを作成したら、開発 API で会社のニーズに合わせてカスタマイズできます。
リリースを作成する手順は、次のとおりです。
450
第 25 章 Live Agent API
1. [設定] で、[カスタマイズ] > [Live Agent] > [リリース] をクリックします。
2. [新規] をクリックします。
3. リリースの名前を入力します。このリリースの名前、つまりバージョンは自動
的に [API 参照名] になります。
4. チャットウィンドウのタイトルを入力します。
5. 訪問者がチャットセッションの終了時にコピーをダウンロードできるようにす
るには、[訪問者にトランスクリプトの保存を許可する] を選択します。
6. リリースに関連付けるサイトを選択します。
7. [[チャット] ウィンドウのブランド画像] で、チャットウィンドウに表示される
画像を選択します。
8. [[モバイルチャット] ウィンドウのブランド画像] で、モバイルデバイスを使用
する訪問者のチャットウィンドウに表示される画像を選択します。
9. [保存] をクリックします。Salesforce は、リリースコードを生成します。
10. リリースコードをコピーして、Live Agent をリリースする各 Web ページに貼り付
けます。最高のパフォーマンスを得るには、このコードを body タグの直前に貼
り付けます。
例: リリースの作成についての詳細は、Salesforce オンラインヘルプの「Live Agent
リリースの作成」を参照してください。
リリース API を使用したリリースアクティビティのロ
グ記録
リリース API を使用して、特定のリリースで発生するアクティビティをログ記録しま
す。
次のリリースメソッドは、特定のリリースでログ記録を有効化するために使用しま
す。ログ記録では、特定のリリースを介して顧客がエージェントとチャットするとき
に、顧客の Web ブラウザで発生するアクティビティに関する情報を保存できます。こ
れらのメソッドは、リリースの作成時に自動生成されるコード内で、追加スクリプト
として追加できます。
451
第 25 章 Live Agent API
enableLogging
enableLogging リリースメソッドは、特定のリリースでログ記録を有効化するため
に使用します。
使用方法
特定のリリースでのログ記録を有効化し、Web ブラウザの JavaScript コンソールで、リ
リース内で発生したアクティビティに関する情報を保存できるようにします。API バー
ジョン 28.0 以降で使用できます。
構文
liveagent.enableLogging();
パラメータ
なし
リリース API を使用したチャットウィンドウのカスタ
マイズ
リリース API を使用して、顧客向けチャットウィンドウのサイズをカスタマイズしま
す。
次のリリースメソッドを使用して、顧客がエージェントとチャットを開始したときに
顧客に表示されるチャットウィンドウの高さと幅をカスタマイズします。いずれのメ
ソッドも、リリースの作成時に自動生成されるコード内で、追加スクリプトとして追
加できます。
setChatWindowHeight
setChatWindowHeight メソッドは、チャットウィンドウの高さをカスタマイズする
ために使用します。
452
第 25 章 Live Agent API
使用方法
顧客に表示されるチャットウィンドウの高さ (ピクセル単位) を設定します。API バー
ジョン 28.0 以降で使用できます。
構文
void setChatWindowHeight(Number height)
パラメータ
名前
型
説明
使用可能なバージョン
height
数値
カスタムチャットウィンドウ API バージョン 28.0 以降で使用
の高さ (ピクセル単位)。
できます。
setChatWindowWidth
setChatWindowWidth メソッドは、チャットウィンドウの幅をカスタマイズするた
めに使用します。
使用方法
顧客に表示されるチャットウィンドウの幅 (ピクセル単位) を設定します。API バージョ
ン 28.0 以降で使用できます。
構文
void setChatWindowWidth(Number width)
パラメータ
名前
型
説明
使用可能なバージョン
width
数値
カスタムチャットウィンドウ API バージョン 28.0 以降で使用
の幅 (ピクセル単位)。
できます。
453
第 25 章 Live Agent API
リリース API を使用したチャット要求の起動
リリース API は、チャット要求の起動方法をカスタマイズするために使用します。
次のリリースメソッドは、顧客がチャットボタンをクリックしたときのチャットの起
動方法と転送方法を指定するために使用します。いずれのメソッドも、リリースの作
成時に自動生成されるコード内で、追加スクリプトとして追加できます。
startChat
startChat メソッドは、新しいウィンドウのボタンからチャットを要求するために
使用します。
使用方法
新しいウィンドウに表示されたボタンからチャットを要求します。
必要に応じて、特定のボタンから指定の userId を持つエージェントにチャットを直
接転送できます。指定のエージェントが対応できない場合、ボタンの転送ルールに戻
すか (true) 否か (false) を指定できます。
構文
void startChat(String buttonId, (optional) String userId, (optional)
Boolean fallback)
パラメータ
名前
型
説明
buttonId
String
新しいウィンドウでチャット API バージョン 28.0 以降で使用
を要求するために使用する できます。
チャットボタンの ID。
(省略可能)
String
ボタンからチャットを直接転 API バージョン 29.0 以降で使用
送するエージェントの
できます。
Salesforce.com ユーザ ID。
userId
使用可能なバージョン
454
第 25 章 Live Agent API
名前
型
(省略可能)
Boolean 指定された sfdcUserId の API バージョン 29.0 以降で使用
エージェントが対応できない できます。
場合、ボタンの転送ルールに
戻すか (true) 否か (false) を
指定します。
fallback
説明
使用可能なバージョン
startChatWithWindow
startChatWithWindow メソッドは、ウィンドウの名前を使用してボタンからチャッ
トを要求するために使用します。
使用方法
表示されたウィンドウ名を使用して、表示されたボタンからチャットを要求します。
API バージョン 28.0 以降で使用できます。
構文
void startChatWithWindow(String buttonId, String windowName,
(optional) String userId, (optional) Boolean fallback)
パラメータ
名前
型
説明
buttonId
String
新しいウィンドウでチャット API バージョン 28.0 以降で使用
を要求するために使用する できます。
チャットボタンの ID。
windowName String
(省略可能)
userId
String
使用可能なバージョン
ウィンドウの名前。
API バージョン 28.0 以降で使用
できます。
ボタンからチャットを直接転 API バージョン 29.0 以降で使用
送するエージェントの
できます。
Salesforce ユーザ ID。
455
第 25 章 Live Agent API
名前
型
(省略可能)
Boolean 指定された sfdcUserId の API バージョン 29.0 以降で使用
エージェントが対応できない できます。
場合、ボタンの転送ルールに
戻すか (true) 否か (false) を
指定します。
fallback
説明
使用可能なバージョン
リリース API を使用した訪問者の詳細のカスタマイズ
リリース API を使用して、チャットを要求した顧客の訪問者情報をカスタマイズしま
す。この情報は、エージェントが顧客とチャットを開始する前に、エージェントに表
示されます。
次のリリースメソッドを使用して、顧客がエージェントとのチャットを要求したとき
の訪問者情報をカスタマイズします。どのメソッドも、リリースの作成時に自動生成
されるコード内で、追加スクリプトとして追加できます。
addCustomDetail
addCustomDetail メソッドは、各チャット訪問者のカスタム詳細を追加するために
使用します。
使用方法
Live Agent コンソールの詳細 Chatlet にチャット訪問者の新しいカスタム詳細を追加しま
す。CustomDetailMapper のインスタンスを返します。API バージョン 28.0 以降で使
用できます。
構文
addCustomDetail(String label, String value, (optional) Boolean
displayToAgent)
456
第 25 章 Live Agent API
パラメータ
名前
型
説明
使用可能なバージョン
label
String
カスタム詳細の表示ラベ
ル。例: "Name"。
API バージョン 28.0 以降で利
用できます。
value
String
カスタム詳細の値。例:
"John Doe".
API バージョン 28.0 以降で利
用できます。
(省略可能)
Boolean 顧客が事前チャットフォー API バージョン 29.0 以降で利
ムに入力したカスタム詳細 用できます。
をエージェントに対して表
示するか (true) 否か
(false) を指定します。
displayToAgent
CustomDetailMapper
CustomDetailMapper オブジェクトは、各チャット訪問者のカスタム詳細を適切な
Live Agent セッションレコードに追加するために使用します。
次のリリースメソッドを使用して、顧客がエージェントとのチャットを要求したとき
の訪問者情報をカスタマイズします。どのメソッドも、リリースの作成時に自動生成
されるコード内で、追加スクリプトとして追加できます。
map
map メソッドは、CustomDetailMapper オブジェクトが訪問者のカスタム詳細の値
をレコードとその項目に対応付けるために使用します。
使用方法
Live Agent コンソールの CRM Chatlet または Salesforce コンソールの関連レコードで、指定
されたエンティティの指定された項目にカスタム詳細の値を対応付けます。API バー
ジョン 28.0 以降で使用できます。
457
第 25 章 Live Agent API
構文
void map(String entityName, String fieldName, Boolean fastFill,
Boolean autoQuery, Boolean exactMatch)
パラメータ
名前
型
説明
使用可能なバージョン
entityName String
カスタム詳細の値を対応付け API バージョン 28.0 以降で使用
る対象のエンティティ。
できます。
fieldName
String
カスタム詳細の値を対応付け API バージョン 28.0 以降で使用
る対象として指定したエン できます。
ティティ内の項目。
fastFill
Boolean エージェントがレコードを作 API バージョン 28.0 以降で使用
成または編集するときに値を できます。
使用して項目を入力できるか
(true)、否か (false) を示し
ます (Live Agent コンソールの
み)。
autoQuery
Boolean 値を含む fieldName を持つ API バージョン 28.0 以降で使用
レコードを見つけるために、 できます。
SOSL クエリ (Live Agent コン
ソールで) または SOQL クエリ
(Salesforce コンソールで) を実
行するか (true)、否か
(false) を指定します。
exactMatch Boolean 比較構文で完全一致を検索す API バージョン 28.0 以降で使用
るか (true)、比較構文にワイ できます。
ルドカードを使用してクエリ
を実行するか (false) を指定
します。
458
第 25 章 Live Agent API
saveToTranscript
saveToTranscript メソッドは、CustomDetailMapper オブジェクトが訪問者のカ
スタム詳細の値を LiveChatTranscript レコードに対応付けるために使用します。
使用方法
チャットの最後で作成された LiveChatTranscript レコードの指定された項目に、カスタム
詳細の値を保存します。API バージョン 28.0 以降で使用できます。
構文
saveToTranscript(String fieldName)
パラメータ
名前
型
説明
使用可能なバージョン
fieldName
String
カスタム詳細の値を保存する API バージョン 28.0 以降で使用
LiveChatTranscript レコード内の できます。
項目。
addCustomDetail.doKnowledgeSearch
knowledgeSearch メソッドは、事前チャットフォームの条件に基づいて Knowledge
One 記事を自動的に検索するために使用します。
使用方法
顧客がエージェントとのチャットを要求すると、事前チャットフォームからカスタム
詳細値が取得されます。エージェントがチャット要求を受け入れると、この値は
Knowledge One ウィジェットの記事を検索するための検索キーワードとして使用されま
す。doKnowledgeSearch() メソッドは、addCustomDetail メソッドの value パ
ラメータを使用して検索を実行します。API バージョン 31.0 以降で使用できます。
459
第 25 章 Live Agent API
構文
liveagent.addCustomDetail(String label, String value, (optional)
Boolean displayToAgent).doKnowledgeSearch()
setName
setName メソッドは、Live Agent コンソールまたは Salesforce コンソールに表示される
訪問者名を上書きするために使用します。
使用方法
Live Agent コンソールまたは Salesforce コンソールに表示される訪問者名を上書きしま
す。API バージョン 28.0 以降で使用できます。
構文
setName(String name)
パラメータ
名前
型
説明
使用可能なバージョン
name
String
Live Agent コンソールまたは API バージョン 28.0 以降で使用
Salesforce コンソールに表示す できます。
る訪問者名。
リリース API を使用したレコードの自動作成
リリース API を使用して、エージェントが顧客とチャットを開始したときに顧客レコー
ドを自動的に検索または作成します。
どのメソッドも、リリースの作成時に自動生成されるコード内で、追加スクリプトと
して追加できます。
460
第 25 章 Live Agent API
findOrCreate
findOrCreate メソッドは、特定の条件に基づいて、既存のレコードを検索するか、
新しいレコードを作成するために使用します。
使用方法
エージェントがチャット要求を受け入れたときに、指定されたタイプのレコードを検
索または作成します。
メモ: findOrCreate メソッドは、エージェントが顧客とチャットを開始したと
きに、既存のレコードの検索または新規レコードの作成を行う API コールを開始
します。リリース API を使用してレコードを検索または作成するには、他の
findOrCreate サブメソッドをコールする前にこのメソッドを使用する必要が
あります。
API バージョン 29.0 以降で使用できます。
構文
liveagent.findOrCreate(String EntityName)
パラメータ
名前
型
EntityName String
説明
使用可能なバージョン
エージェントが顧客との
API バージョン 29.0 以降で使用
チャットを受け入れたとき できます。
に、検索または作成するレ
コードのタイプ。例: 取引先
責任者レコード。
findOrCreate.map
findOrCreate.map メソッドは、特定の顧客の詳細を含むレコードを検索または作
成するために使用します。
461
第 25 章 Live Agent API
使用方法
addCustomDetail リリース API メソッドで指定された顧客データを含むレコードを
検索または作成します。このメソッドは、カスタム詳細の値を、Salesforce コンソール
の指定レコードの項目に対応付けます。
findOrCreate.map メソッドは、適切なレコードを検索するために何度でもコール
できます。検索対象の各項目および対応するカスタム詳細値に対してメソッドを 1 回
コールします。
API バージョン 29.0 以降で使用できます。
構文
liveagent.findOrCreate(Object EntityName).map(String FieldName,
String DetailName, Boolean doFind, Boolean isExactMatch, Boolean
doCreate)
パラメータ
名前
型
説明
FieldName
String
対応するカスタム詳細
API バージョン 29.0 以降で使用
DetailName に対応付けるレ できます。
コード EntityName の項目
の名前。
DetailName String
対応する項目 FieldName に API バージョン 29.0 以降で使用
対応付けるカスタム詳細の できます。
値。
doFind
使用可能なバージョン
Boolean 項目 FieldName のカスタム API バージョン 29.0 以降で使用
詳細 DetailName を含むレ できます。
コードを検索するか (true)、
否か (false) を指定します。
isExactMatch Boolean 項目 FieldName で指定した API バージョン 29.0 以降で使用
カスタム詳細 DetailName できます。
の正確な値を含むレコードを
462
第 25 章 Live Agent API
名前
型
説明
使用可能なバージョン
検索するか (true)、否か
(false) を指定します。
doCreate
Boolean 項目 FieldName で検出され API バージョン 29.0 以降で使用
なかった場合に、カスタム詳 できます。
細 DetailName を持つ新規
レコードを作成するか
(true)、否か (false) を指定
します。
findOrCreate.saveToTranscript
findOrCreate.saveToTranscript メソッドは、検索または作成したレコードを、
チャットに関連付けられたチャットトランスクリプトに保存するために使用します。
使用方法
findOrCreate および findOrCreate.map リリース API メソッドを使用して検索ま
たは作成したレコードを、チャットに関連付けられたチャットトランスクリプトに保
存します。
API バージョン 29.0 以降で使用できます。
構文
liveagent.findOrCreate(String EntityName).saveToTranscript(String
TranscriptFieldName)
パラメータ
名前
型
TranscriptFieldName String
説明
使用可能なバージョン
検索または作成したレコー API バージョン 29.0 以降で使
ドの ID の保存先のチャッ 用できます。
トトランスクリプトレコー
ドの項目の名前。
463
第 25 章 Live Agent API
findOrCreate.showOnCreate
findOrCreate.showOnCreate メソッドは、作成したレコードを Salesforce コンソー
ルのサブタブで自動的に開くために使用します。
使用方法
findOrCreate および findOrCreate.map リリース API メソッドを使用して作成し
たレコードを、Salesforce コンソールのサブタブで自動的に開きます。
API バージョン 29.0 以降で使用できます。
構文
liveagent.findOrCreate(String EntityName).showOnCreate()
findOrCreate.linkToEntity
findOrCreate.linkToEntity メソッドは、検索または作成したレコードを別のレ
コードタイプにリンクするために使用します。
使用方法
findOrCreate および findOrCreate.map リリース API メソッドを使用して検索ま
たは作成したレコードを、別の findOrCreate API コールを使用して作成した、レ
コードタイプが異なる別のレコードにリンクします。たとえば、組織内で検出した
ケースレコードを、作成した取引先責任者レコードにリンクできます。
メモ: レコードは、findOrCreate API コールを使用して親レコードが作成され
ている場合にのみリンクできます。子レコードは、findOrCreate.linkToEntity
メソッドを使用して検出したレコードにリンクできません。
API バージョン 29.0 以降で使用できます。
構文
liveagent.findOrCreate(String EntityName).linkToEntity(String
EntityName, String FieldName)
464
第 25 章 Live Agent API
パラメータ
名前
型
説明
使用可能なバージョン
EntityName String
検索または作成した子レコー API バージョン 29.0 以降で使用
ドのリンク先のレコードタイ できます。
プ。
String
検索または作成した子レコー API バージョン 29.0 以降で使用
ドの ID の保存先のレコード できます。
EntityName の項目名。
FieldName
レコード作成のリリース API のコードサンプル
このコードサンプルを使用して、レコードの自動作成がLive Agentリリースでどのよう
に動作するかをテストおよびプレビューします。
次のコードは、以下のメソッドを使用してエージェントが顧客とチャットを開始した
ときにレコードを検索および作成します。
• findOrCreate
• findOrCreate.map
• findOrCreate.saveToTranscript
• findOrCreate.linkToEntity
• findOrCreate.showOnCreate
liveagent.addCustomDetail("First Name", "Ryan");
liveagent.addCustomDetail("Last Name", "Smith");
liveagent.addCustomDetail("Phone Number", "555-1212");
liveagent.addCustomDetail("Case Subject", "Problem with my iPhone");
liveagent.addCustomDetail("Case Status", "New", false);
liveagent.findOrCreate("Contact").map("FirstName", "First Name", true,
true, true).map("LastName", "Last Name", true, true, true).map("Phone",
"Phone Number", false,
false,true).saveToTranscript("contactId").showOnCreate().linkToEntity("Case",
465
第 25 章 Live Agent API
"ContactId");
liveagent.findOrCreate("Case").map("Subject", "Case Subject", true,
false, true).map("Status", "Case Status", false, false,
true).showOnCreate();
リリース API を使用したチャットボタンのカスタマイ
ズ
リリース API を使用して、Web サイトに表示されるチャットボタンをカスタマイズし
ます。
次のリリースメソッドを使用して、チャットボタンをカスタマイズします。どのメ
ソッドも、リリースの作成時に自動生成されるコード内で、追加スクリプトとして追
加できます。
showWhenOnline
showWhenOnline メソッドは、特定のボタンがオンラインの場合に顧客に表示され
る内容を指定するために使用します。
使用方法
指定したボタンがオンラインの場合に、特定の要素を表示します。API バージョン 28.0
以降で使用できます。
構文
void showWhenOnline(String buttonId, Object element, (optional)
String userId)
466
第 25 章 Live Agent API
パラメータ
名前
型
説明
buttonId
String
ボタンに関連付けられている API バージョン 28.0 以降で使用
エージェントがチャットに対 できます。
応できる場合に、指定した
element オブジェクトを表
示するチャットボタンの ID。
element
Object
指定したボタンがオンライン API バージョン 28.0 以降で使用
の場合に表示する要素。
できます。
(省略可能)
String
ボタンに関連付けるエージェ API バージョン 29.0 以降で使用
ントの ID。エージェントが対 できます。
応できる場合に、element
オブジェクトが表示されま
す。
userId
使用可能なバージョン
パラメータにボタン ID を指定してエージェント ID は指定しない場合、要素はボタン
がオンラインの場合にのみ表示されます。
パラメータにエージェント ID を指定してボタン ID は指定しない場合、要素はエージェ
ントがオンラインの場合にのみ表示されます。たとえば、次の構文は、エージェント
のオンライン状況を追跡し、エージェントが対応できる場合にボタンをオンラインに
設定します。ただし、エージェントが対応できない場合は、ボタンはオフラインに設
定されます。
liveagent.showWhenOnline('005xx000001Sv1m',
document.getElementById('liveagent_button_toAgent_online')
ボタン ID とエージェント ID を指定する場合、要素はボタンとエージェントのいずれ
かがオンラインの場合に表示されます。たとえば、次の構文は、エージェントとボタ
ンの状況を追跡して、いずれかが対応できる場合に要素を表示します。
liveagent.showWhenOnline('573xx0000000006',
document.getElementById('liveagent_button_online_573xx0000000006_USER1'),
'005xx000001Sv1m');
467
第 25 章 Live Agent API
showWhenOffline
showWhenOffline メソッドは、特定のボタンがオフラインの場合に顧客に表示され
る内容を指定するために使用します。
使用方法
指定したボタンがオフラインの場合に、特定の要素を表示します。API バージョン 28.0
以降で使用できます。
構文
void showWhenOffline(String buttonId, Object element, (optional)
String userId)
パラメータ
名前
型
説明
buttonId
String
エージェントがチャットに対 API バージョン 28.0 以降で使用
応できない場合に、指定した できます。
element オブジェクトを表
示するチャットボタンの ID。
element
Object
指定したボタンがオフライン API バージョン 28.0 以降で使用
の場合に表示する要素。
できます。
(省略可能)
String
ボタンに関連付けるエージェ API バージョン 29.0 以降で使用
ントの ID。このエージェント できます。
が対応できない場合に、
element オブジェクトが表
示されます。
userId
使用可能なバージョン
パラメータにボタン ID を指定してエージェント ID は指定しない場合、要素はボタン
がオフラインの場合にのみ表示されます。
パラメータにエージェント ID を指定してボタン ID は指定しない場合、要素はエージェ
ントがオフラインの場合にのみ表示されます。たとえば、次の構文は、エージェント
468
第 25 章 Live Agent API
のオンライン状況を追跡し、エージェントが対応できない場合はボタンをオフライン
に設定します。
liveagent.showWhenOffline('005xx000001Sv1m',
document.getElementById('liveagent_button_toAgent_offline')
ボタン ID とエージェント ID を指定する場合、要素はボタンとエージェントのいずれ
も対応できない場合に表示されます。たとえば、次の構文は、エージェントとボタン
の状況を追跡して、いずれも対応できない場合に要素を表示します。
liveagent.showWhenOffline('573xx0000000006',
document.getElementById('liveagent_button_offline_573xx0000000006_USER1'),
'005xx000001Sv1m');
addButtonEventHandler
addButtonEventHandler メソッドは、特定のイベントが発生したときのチャットボ
タンの動作を定義するために使用します。
使用方法
次のイベントが発生したときのチャットボタンの動作を定義します。
• チャットに対応できるエージェントがいる。
• チャットに対応できるエージェントがいない。
API バージョン 28.0 以降で使用できます。
構文
void addButtonEventHandler(String buttonId, Function callback)
パラメータ
名前
型
説明
使用可能なバージョン
buttonId
String
特定のイベントが発生したと API バージョン 28.0 以降で使用
きの動作を定義するチャット できます。
ボタンの ID。
469
第 25 章 Live Agent API
名前
型
説明
使用可能なバージョン
callback
function 特定のイベントが発生したと API バージョン 28.0 以降で使用
きにコールする関数。必要な できます。
イベントタイプ (ページ470)そ
れぞれにボタンの動作を指定
する必要があります。
イベントタイプ
次のイベントタイプを callback 関数に取り込み、特定のイベントが発生したときの
ボタンの動作をカスタマイズします。次の各イベントタイプにボタンの動作を指定す
る必要があります。
関数
イベントタイプ
callback BUTTON_AVAILABLE
構文
説明
liveagent.BUTTON_EVENT.BUTTON_AVAILABLE 適切なスキ
ルを持つ
エージェン
トがチャッ
トに対応で
きるときな
どの、顧客
がエージェ
ントと
チャットで
きる条件が
満たされた
ときのボタ
ンの動作を
指定しま
す。
BUTTON_UNAVAILABLE
liveagent.BUTTON_EVENT.BUTTON_UNAVAILABLE エージェン
トがチャッ
トに対応で
きない場合
470
第 25 章 Live Agent API
関数
イベントタイプ
構文
説明
のボタンの
動作を指定
します。
リリース API を使用した自動チャット招待のカスタマ
イズ
リリース API を使用して、Web サイトで顧客に表示される自動チャット招待をカスタ
マイズします。
次のリリースメソッドを使用して、自動チャット招待をカスタマイズします。
rejectChat
rejectChat メソッドは、顧客に送信された招待を却下して撤回するために使用しま
す。
使用方法
招待を却下して撤回します。
API バージョン 28.0 以降で使用できます。
構文
void rejectChat(String buttonId)
パラメータ
名前
型
説明
使用可能なバージョン
buttonId
String
却下するチャットのチャット API バージョン 28.0 以降で使用
ボタンの ID。
できます。
471
第 25 章 Live Agent API
addButtonEventHandler
addButtonEventHandler メソッドは、特定のイベントが発生したときの自動招待の
動作を定義するために使用します。
使用方法
次のイベントが発生したときの招待の動作を定義します。
• 招待が画面に表示されるための条件が満たされる。
• 招待が画面に表示されるための条件が満たされない。
• 顧客がチャットの招待を受諾する。
• 顧客がチャットの招待を却下する。
API バージョン 28.0 以降で使用できます。
構文
void addButtonEventHandler(String buttonId, Function callback)
パラメータ
名前
型
説明
使用可能なバージョン
buttonId
String
特定のイベントが発生したと API バージョン 28.0 以降で使用
きの動作を定義する自動招待 できます。
に関連付けられたチャットボ
タンの ID。
callback
function 特定のイベントが発生したと API バージョン 28.0 以降で使用
きにコールする関数。必要な できます。
イベントタイプ (ページ473)そ
れぞれに招待の動作を指定す
る必要があります。
472
第 25 章 Live Agent API
イベントタイプ
次のイベントタイプを callback 関数に取り込み、特定のイベントが発生したときの
招待の動作をカスタマイズします。次のイベントタイプそれぞれに招待の動作を指定
する必要があります。
関数
イベントタイプ
callback BUTTON_AVAILABLE
構文
説明
liveagent.BUTTON_EVENT.BUTTON_AVAILABLE 招待が画面
に表示され
るための条
件が満たさ
れた場合の
自動招待の
動作を指定
します。
BUTTON_UNAVAILABLE
liveagent.BUTTON_EVENT.BUTTON_UNAVAILABLE エージェン
トがチャッ
トに対応で
きない場合
の自動招待
の動作を指
定します。
BUTTON_ACCEPTED
liveagent.BUTTON_EVENT.BUTTON_ACCEPTED 顧客が招待
を受諾した
場合の自動
招待の動作
を指定しま
す。
BUTTON_REJECTED
liveagent.BUTTON_EVENT.BUTTON_REJECTED 顧客が招待
を却下した
場合の自動
招待の動作
を指定しま
す。
473
第 25 章 Live Agent API
setCustomVariable
setCustomVariable メソッドは、自動招待が顧客に送信されるために満たす必要が
ある送信ルールに、カスタマイズされた条件を作成するために使用します。
使用方法
自動招待が顧客に送信されるために満たす必要がある送信ルールに、カスタマイズさ
れた条件を作成します。送信ルールの条件に使用されるカスタム変数の比較値を指定
します。API バージョン 28.0 以降で使用できます。
構文
void setCustomVariable(String variableName, Object value)
パラメータ
名前
型
variableName String
value
Object
説明
使用可能なバージョン
カスタム送信ルールのカスタ API バージョン 28.0 以降で使用
マイズされた条件の名前。 できます。
カスタム送信ルールの比較
値。
API バージョン 28.0 以降で使用
できます。
自動チャット招待のコードサンプル
このコードサンプルを使用して、Web サイトで自動チャット招待がどのように動作す
るかをテストおよびプレビューします。
カスタマイズされた招待を Web サイトに表示するために addButtonEventHandler()
メソッドを使用する自動チャット招待のコードを次に示します。この招待では、適切
なスキルを持つエージェントがチャットに対応できる場合に、顧客がエージェントと
チャットを開始できます。
<apex:page>
<div id="liveagent_invite_button_573x0000000001O" style="display: none;
474
第 25 章 Live Agent API
position: fixed; border: 2px solid darkblue; border-radius: 5px;
background-color: lightblue; height: 100px; width: 200px;">
<div style="cursor: pointer; padding: 5px; right: 0px;
position: absolute; color: darkred; font-weight: bold;"
onclick="liveagent.rejectChat('573x0000000001O')">X</div>
<div style="cursor: pointer; top: 42px; left: 65px; position: absolute;
font-weight: bold; font-size: 16px;"
onclick="liveagent.startChat('573x0000000001O')">Start Chat</div>
</div>
<script type='text/javascript'
src='https://c.la1s1.saleforceliveagent.com/content/g/deployment.js'>
</script>
<script type='text/javascript'>
function buttonCallback(e) {
if (e == liveagent.BUTTON_EVENT.BUTTON_AVAILABLE) {
document.getElementById('liveagent_invite_button_573x0000000001O').style.display
= '';
document.getElementById('liveagent_invite_button_573x0000000001O').style.left
=
475
第 25 章 Live Agent API
'300px';
document.getElementById('liveagent_invite_button_573x0000000001O').style.top
=
'200px';
}
if (e == liveagent.BUTTON_EVENT.BUTTON_UNAVAILABLE) {
document.getElementById('liveagent_invite_button_573x0000000001O').style.display
=
'none';
}
if (e == liveagent.BUTTON_EVENT.BUTTON_ACCEPTED) {
document.getElementById('liveagent_invite_button_573x0000000001O').style.display
=
'none';
}
if (e == liveagent.BUTTON_EVENT.BUTTON_REJECTED) {
document.getElementById('liveagent_invite_button_573x0000000001O').style.display
=
'none';
}
}
liveagent.addButtonEventHandler('573x0000000001O', buttonCallback);
476
第 25 章 Live Agent API
liveagent.init('https://d.la1s1.salesforceliveagent.com/chat',
'572x00000000001',
'00Dx00000001gEH');
</script>
</apex:page>
上記のコードの結果は、次のような招待になります。
開発 API のコードサンプル
リリース API がリリースのカスタマイズにどのように役立つかをテストおよびプレ
ビューします。
次のコードサンプルでは、次の開発 API メソッドを使用するチャットウィンドウを示
します。
• startChat
• showWhenOnline
• showWhenOffline
• addCustomDetail
• setName
• map
477
第 25 章 Live Agent API
• setChatWindowWidth
• setChatWindowHeight
• doKnowledgeSearch
<apex:page >
<h1>Welcome!</h1>
Thank you for contacting customer support.
<!-- START Button code -->
<img id="liveagent_button_online_573D000000000Ar" style="display:
none;
border: 0px none; cursor: pointer"
onclick="liveagent.startChat('573D000000000Ar')"
src="https://na1.salesforce.com/resource/1319587702000/Chat_Online"
/>
<img id="liveagent_button_offline_573D000000000Ar" style="display:
none;
border: 0px none;
"src="https://na1.salesforce.com/resource/1319587748000/Chat_Offline"
/>
<script type="text/javascript">
if (!window._laq) { window._laq = []; }
window._laq.push(function(){liveagent.showWhenOnline('573D000000000Ar',
478
第 25 章 Live Agent API
document.getElementById('liveagent_button_online_573D000000000Ar'));
liveagent.showWhenOffline('573D000000000Ar',
document.getElementById('liveagent_button_offline_573D000000000Ar'));
});</script>
<!-- END Button code -->
<!-- Deployment code -->
<script type='text/javascript'
src='https://c.la1s1.saleforceliveagent.com/content/g/deployment.js'></script>
<script type='text/javascript'>
// An auto query that searches contacts whose email field matches
"[email protected]"
liveagent.addCustomDetail('Contact E-mail', '[email protected]');
liveagent.findOrCreate('Contact').map('Email','Contact
E-mail',true,false,false);
// Conducts a Knowledge One search on the provided value; in this
case,
// searches Knowledge One articles for the term "Problems with my
iPhone"
liveagent.addCustomDetail('Case Subject', 'Problem with my
iPhone').doKnowledgeSearch();
479
第 25 章 Live Agent API
// A fast-fill to populate a contact’s name with "John Doe"
liveagent.addCustomDetail('Contact Name', 'John Doe');
liveagent.findOrCreate('Contact').map('FirstName','Contact
Name',false,false,false);
// Saves the custom detail to a custom field on LiveChatTranscript
at the end of a chat
liveagent.addCustomDetail('Company',
'Acme').saveToTranscript('Company__c');
// Overrides the display name of the visitor in the agent console
when engaged in a chat
liveagent.setName('John Doe');
// Sets the width of the chat window to 500px
liveagent.setChatWindowWidth(500);
// Sets the height of the chat window to 500px
liveagent.setChatWindowHeight(500);
liveagent.init('https://d.la1s1.salesforceliveagent.com/chat',
'572D0000000002R',
'00DD0000000JXbY');
</script>
</apex:page>
このリリースコードの結果は、次のようなページになります。
480
第 25 章 Live Agent API
事前チャット API を使用したチャットの詳細への
アクセス
事前チャット API を使用して、リリース API から顧客の詳細にアクセスし、事前チャッ
トフォームに取り込みます。
preChatInit
preChatInit メソッドは、addCustomDetail リリース API メソッドを使用してチャッ
トに渡されたカスタム詳細にアクセスするために使用します。
使用方法
addCustomDetail リリース API メソッドを使用してチャットに渡されたカスタム詳
細を抽出し、それを事前チャットフォームに統合します。
API バージョン 29.0 以降で使用できます。
構文
liveagent.details.preChatInit(String chatUrl, function
detailCallback, (optional) String chatFormName)
パラメータ
名前
型
説明
使用可能なバージョン
chatUrl
String
カスタム詳細を取得する
チャットの URL。
API バージョン 29.0 以降で使
用できます。
detailCallback
String
メソッドの完了時にコー
ルされる JavaScript 関数の
名前。
API バージョン 29.0 以降で使
用できます。
481
第 25 章 Live Agent API
名前
型
説明
使用可能なバージョン
(省略可能)
String
カスタム詳細を取り込む
事前チャットフォームの
HTML form タグの名前。
API バージョン 29.0 以降で使
用できます。
chatFormName
応答
名前
型
説明
使用可能なバージョン
details
Object
preChatInit メソッドを
API バージョン 29.0 以降で使
用できます。
使用して事前チャット
フォームに格納されたすべ
てのカスタム詳細を含むオ
ブジェクト。
details オブジェクトの構造は、次のオブジェクト例のようになります。
{
"geoLocation":{
"countryCode":"US",
"countryName":"United States",
"longitude":-122.4294,
"organization":"SALESFORCE.COM",
"latitude":37.764496,
"region":"CA",
"city":"San Francisco"
},
482
第 25 章 Live Agent API
"customDetails":[
{
"label":"Email",
"value":"[email protected]",
"transcriptFields":["Email__c"],
"entityMaps":[
{
"fieldName":"Email",
"isAutoQueryable":true,
"entityName":"Contact",
"isExactMatchable":true,
"isFastFillable":false
}]
},
{
"label":"Name",
"value":"Sonic H.",
"transcriptFields":[],
"entityMaps":[]
}
],
"visitorId":"251a5956-bcbc-433d-b822-a87c062e681c"
483
第 25 章 Live Agent API
}
detailCallback
detailCallback メソッドは、preChatInit メソッドが details オブジェクトを
返した後に発生する動作を指定します。
構文
パラ
説明
メータ
function
myCallBack(details)
{
使用可能なバージョン
details preChatInit メソッドを使 API バージョン 29.0 以降で使
用してカスタム詳細が取得 用できます。
された後に実行されるアク
ションを指定します。
//
Customer
specific code
}
事前チャット API を使用してレコードを自動作成
する
事前チャット API を使用して、顧客が事前チャットフォームを完了したときに顧客レ
コードを自動的に検索または作成します。
findOrCreate.map
findOrCreate.map メソッドは、特定の顧客の詳細を含むレコードを検索または作
成するために使用します。
484
第 25 章 Live Agent API
使用方法
顧客が完了した事前チャットフォームで指定された顧客データを含むレコードを検索
または作成します。このメソッドは、カスタム詳細の値を、Salesforce コンソールの指
定レコードの項目に対応付けます。
findOrCreate.map メソッドは、適切なレコードを検索するために何度でもコール
できます。複数の項目とそれに対応する詳細をリストして、レコード内の適切な項目
に詳細の値を対応付けることができます。
API バージョン 29.0 以降で使用できます。
構文
<input type= "hidden" name= "liveagent.prechat.findorcreate.map:
String entityName" value= "String fieldName, String detailName;" />
パラメータ
名前
型
entityName String
説明
使用可能なバージョン
エージェントが顧客との
チャットを受け入れたとき
に、検索または作成するレ
コードのタイプ。例: 取引先
責任者レコード。
API バージョン 29.0 以降で利用
できます。
String
対応するカスタム詳細 value API バージョン 29.0 以降で利用
できます。
に対応付けるレコード
EntityName の項目の名前。
detailName String
対応する項目 fieldName に API バージョン 29.0 以降で利用
対応付けるカスタム詳細の できます。
値。
fieldName
485
第 25 章 Live Agent API
findOrCreate.map.doFind
findOrCreate.map.doFind メソッドは、顧客が事前チャットフォームを完了した
ときに既存の顧客レコードの検索に使用する項目を指定するために使用します。
使用方法
既存のレコードを検索するために使用する、findOrCreate.map メソッドの項目を
指定します。レコード内の 1 つ以上の項目を検索できます。
API バージョン 29.0 以降で使用できます。
構文
<input type= "hidden" name=
"liveagent.prechat.findorcreate.map.doFind: String entityName" value=
"String fieldName, Boolean find;"/>
パラメータ
名前
型
entityName String
説明
使用可能なバージョン
エージェントが顧客との
チャットを受け入れたとき
に、検索または作成するレ
コードのタイプ。例: 取引先
責任者レコード。
API バージョン 29.0 以降で利用
できます。
fieldName
String
find
Boolean 項目 fieldName を含む既存 API バージョン 29.0 以降で利用
できます。
のレコードを検索するか
(true)、否か (false) を指定
します。
既存のレコードで検索する項 API バージョン 29.0 以降で利用
目の名前。
できます。
メモ: 指定する必要が
あるのは、find が
true に一致する項目
486
第 25 章 Live Agent API
名前
型
説明
使用可能なバージョン
のみです。メソッド
は、find が false に
一致する項目を含むレ
コードは検索しませ
ん。
findOrCreate.map.isExactMatch
findOrCreate.map.isExactMatch メソッドは、findOrCreate.map メソッドを使
用して検索を実行するときに、項目値が既存のレコードの項目値と完全に一致する必
要があるかどうかを指定するために使用します。
使用方法
既存のレコードを検索するときに項目値が完全に一致する必要がある
findOrCreate.map メソッドの項目を指定します。レコード内の 1 つ以上の項目に
対して指定できます。
API バージョン 29.0 以降で使用できます。
構文
<input type= "hidden" name=
"liveagent.prechat.findorcreate.map.isExactMatch: String entityName"
value= "String fieldName, Boolean exactMatch;" />
パラメータ
名前
型
entityName String
説明
使用可能なバージョン
エージェントが顧客との
チャットを受け入れたとき
に、検索または作成するレ
コードのタイプ。例: 取引先
責任者レコード。
API バージョン 29.0 以降で利用
できます。
487
第 25 章 Live Agent API
名前
型
説明
使用可能なバージョン
fieldName
String
既存のレコードで検索する項 API バージョン 29.0 以降で利用
目の名前。
できます。
find
Boolean 完全に一致する項目
API バージョン 29.0 以降で利用
fieldName を含む既存のレ できます。
コードを検索するか (true)、
否か (false) を指定します。
メモ: 指定する必要が
あるのは、
exactMatch が true
に一致する項目のみで
す。メソッドは、
exactMatch が false
に一致する項目を含む
レコードは検索しませ
ん。
findOrCreate.map.doCreate
findOrCreate.map.doCreate メソッドは、既存のレコードが見つからない場合に
レコードを新規作成するために使用する、findOrCreate.map メソッドの項目を指
定するために使用します。
使用方法
既存のレコードが見つからない場合にレコードを新規作成するために使用する、
findOrCreate.map メソッドの項目を指定します。レコードを新規作成するには 1 つ
以上の項目を指定できます。
API バージョン 29.0 以降で使用できます。
488
第 25 章 Live Agent API
構文
<input type= "hidden" name=
"liveagent.prechat.findorcreate.map.doCreate: String entityName"
value= "String fieldName, Boolean create;" />
パラメータ
名前
型
説明
使用可能なバージョン
entityName String
エージェントが顧客との
API バージョン 29.0 以降で利用
チャットを受け入れたとき、 できます。
既存のレコードが見つからな
い場合に作成するレコードの
タイプ。例: 取引先責任者レ
コード。
fieldName
String
新規レコードに含める項目の API バージョン 29.0 以降で利用
名前。
できます。
create
Boolean 項目 fieldName を含む新規 API バージョン 29.0 以降で利用
できます。
レコードを作成するか
(true)、否か (false) を指定
します。
メモ: 指定する必要が
あるのは、create が
true に一致する項目
のみです。このメソッ
ドは、create が
false に一致する項目
は作成しません。
findOrCreate.saveToTranscript
findOrCreate.saveToTranscript メソッドは、検索または作成したレコードを、
チャットに関連付けられたチャットトランスクリプトに保存するために使用します。
489
第 25 章 Live Agent API
使用方法
findOrCreate.map.doCreate または findOrCreate.map.doFind 事前チャット
API メソッドを使用して検索または作成したレコードを、チャット終了時に、チャッ
トに関連付けられたチャットトランスクリプトに保存します。
API バージョン 29.0 以降で使用できます。
構文
<input type="hidden" name=
"liveagent.prechat.findorcreate.saveToTranscript: String entityName"
value= "String transcriptFieldName" />
パラメータ
名前
型
説明
使用可能なバージョン
entityName
String
エージェントが顧客との API バージョン 29.0 以降で利
チャットを受け入れたとき 用できます。
に、検索または作成するレ
コードのタイプ。例: 取引
先責任者レコード。
transcriptFieldName String
検索または作成したレコー API バージョン 29.0 以降で利
ドの ID の保存先のチャット 用できます。
トランスクリプトレコード
の項目の名前。
findOrCreate.showOnCreate
findOrCreate.showOnCreate メソッドは、作成したレコードを Salesforce コンソー
ルのサブタブで自動的に開くために使用します。
490
第 25 章 Live Agent API
使用方法
findOrCreate.map.doCreate および findOrCreate.map.doFind 事前チャット
API メソッドを使用して検索または作成したレコードを、Salesforce コンソールのサブタ
ブで自動的に開きます。
API バージョン 29.0 以降で使用できます。
構文
<input type= "hidden" name=
"liveagent.prechat.findorcreate.showOnCreate: String entityName"
value= "Boolean show" />
パラメータ
名前
型
entityName String
show
説明
使用可能なバージョン
エージェントが顧客との
チャットを受け入れたとき
に、検索または作成するレ
コードのタイプ。例: 取引先
責任者レコード。
API バージョン 29.0 以降で利用
できます。
Boolean 作成したレコードを Salesforce API バージョン 29.0 以降で利用
コンソールのサブタブで表示 できます。
するか (true) 否か (false) を
指定します。
findOrCreate.linkToEntity
findOrCreate.linkToEntity メソッドは、検索または作成したレコードを別のレ
コードタイプにリンクするために使用します。
491
第 25 章 Live Agent API
使用方法
findOrCreate.map.doFind および findOrCreate.map.doCreate 事前チャット
API メソッドを使用して検索または作成したレコードを、別の findOrCreate.map API
コールを使用して作成した、レコードタイプが異なる別のレコードにリンクします。
たとえば、組織内で検出したケースレコードを、作成した取引先責任者レコードにリ
ンクできます。
findOrCreate API コールを使用して作成したレコードの項目は、
findOrCreate.linkToEntity メソッドを使用して入力することができません。代
わりに、findOrCreate.map メソッドを使用して、レコードの項目値を更新します。
メモ: レコードは、findOrCreate API コールを使用して親レコードが作成され
ている場合にのみリンクできます。子レコードは、findOrCreate.linkToEntity
メソッドを使用して検出したレコードにリンクできません。
API バージョン 29.0 以降で使用できます。
構文
<input type= "hidden" name=
"liveagent.prechat.findorcreate.linkToEntity: String entityName"
value= "String parentEntityName, String fieldName" />
パラメータ
名前
型
説明
使用可能なバージョン
entityName
String
検索または作成した子レコー API バージョン 29.0 以降で利
ドのリンク先のレコードタイ 用できます。
プ。
parentEntityName String
検索または作成した子レコー API バージョン 29.0 以降で利
ドにリンクする親レコードタ 用できます。
イプ。
492
第 25 章 Live Agent API
名前
型
説明
使用可能なバージョン
fieldName
String
検索または作成した子レコー API バージョン 29.0 以降で利
ドの ID の保存先のレコード 用できます。
parentEntityName の項目
名。
findOrCreate.displayToAgent
findOrCreate.displayToAgent メソッドは、エージェントがチャット要求を受信
したときに、エージェントの [詳細] タブにどの事前チャット詳細を表示するか指定す
るために使用します。
使用方法
エージェントがチャット要求を受信したときに、エージェントのSalesforce コンソール
の [詳細] タブにどの事前チャット詳細を表示するか指定します。
API バージョン 29.0 以降で使用できます。
構文
<input type= "hidden" name=
"liveagent.prechat.findorcreate.displayToAgent: String detailName"
value= "Boolean display" />
パラメータ
名前
型
detailName String
説明
使用可能なバージョン
エージェントがチャット要求 API バージョン 29.0 以降で利用
を受信したときにエージェン できます。
トに対して表示される詳細の
名前。
493
第 25 章 Live Agent API
名前
型
説明
使用可能なバージョン
display
Boolean 顧客詳細をエージェントの API バージョン 29.0 以降で利用
Salesforce コンソールの [詳細] できます。
タブに表示するか (true)、否
か (false) を指定します。
メモ: 指定する必要が
あるのは、display が
false に一致する詳細
のみです。このメソッ
ドは、display が
false に一致する詳細
は表示しません。
display パラメータの
値を指定しない場合、
デフォルト値は true
に設定されます。
レコード作成の事前チャット API のコードサンプル
このコードサンプルを使用して、顧客が事前チャットフォームを完了したときにレ
コードがどのように自動作成されるかをテストおよびプレビューします。
次のコードは、以下のメソッドを使用して顧客が事前チャットフォームを完了したと
きにレコードを検索および作成します。
• findOrCreate.map
• findOrCreate.map.doFind
• findOrCreate.map.isExactMatch
• findOrCreate.map.doCreate
• findOrCreate.saveToTranscript
• findOrCreate.showOnCreate
• findOrCreate.linkToEntity
<form method="post" action="#">
494
第 25 章 Live Agent API
<label>First Name: </label> <input type='text'
name='liveagent.prechat:ContactFirstName' /><br />
<label>Last Name: </label> <input type='text'
name='liveagent.prechat:ContactLastName' /><br />
<label>Subject: </label> <input type='text'
name='liveagent.prechat:CaseSubject' /><br />
<input type='hidden" name="liveagent.prechat:CaseStatus" value="New"
/><br />
<input type="hidden" name="liveagent.prechat.findorcreate.map:Contact"
value="FirstName,ContactFirstName;LastName,ContactLastName" />
<input type="hidden"
name="liveagent.prechat.findorcreate.map.doFind:Contact"
value="FirstName,true;LastName,true" />
<input type="hidden"
name="liveagent.prechat.findorcreate.map.isExactMatch:Contact"
value="FirstName,true;LastName,true" />
<input type="hidden"
name="liveagent.prechat.findorcreate.map.doCreate:Contact"
value="FirstName,true;LastName,true" />
<input type="hidden"
name="liveagent.prechat.findorcreate.saveToTranscript:Contact"
value="ContactId" />
<input type="hidden"
name="liveagent.prechat.findorcreate.showOnCreate:Contact" value="true"
/>
<input type="hidden"
name="liveagent.prechat.findorcreate.linkToEntity:Contact"
value="Case,ContactId" />
<input type="hidden" name="liveagent.prechat.findorcreate.map:Case"
value="Subject,CaseSubject;Status,CaseStatus" />
<input type="hidden"
name="liveagent.prechat.findorcreate.map.doCreate:Case"
495
第 25 章 Live Agent API
value="Subject,true;Status,true" />
<input type="submit" value="Submit">
</form>
リソース
Live Agent API に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) で検索してください。
• Live Agent 開発者ガイド
• Live Agent REST API 開発者ガイド
496
第 26 章
Salesforce コンソールインテグレー
ションツールキット
Salesforce コンソールは、Salesforce でレコードの検索、更新、および作成をすばやく行
う必要のある、変化の速い環境にあるユーザ向けに設計されています。
Salesforce コンソールインテグレーションツールキットでは、Salesforce コンソールにプ
ログラムを使用してアクセスできるため、ビジネスニーズに応じてそれを拡張するこ
とができます。Salesforce コンソールインテグレーションツールキットを使用すると、
コンソールのタブの開閉によって、ビジネスプロセスを合理化できます。たとえば、
1 つのタブ内の同じウィンドウで外部アプリケーションを開いた状態で、サードパー
ティシステムとコンソールを統合することができます。
Salesforce コンソールインテグレーションツールキットは、ブラウザベースの JavaScript
API です。ブラウザをクライアントとして使用して、コンソールにタブとしてページ
を表示します。
Salesforce コンソールインテグレーションツールキットは、各リリースの API バージョ
ンと一致します。たとえば、SOAP API の現在のバージョンが 28.0 である場合、Salesforce
コンソールインテグレーションツールキットのバージョン 28.0 も存在します。
このガイドでは、Salesforce コンソールインテグレーションツールキットと使用可能な
API メソッドの概要について説明します。詳細は、『Salesforce コンソールインテグレー
ションツールキット開発者ガイド』を参照してください。
サポートされるブラウザ
Salesforce コンソールインテグレーションツールキットでは、次のブラウザがサポート
されます。
• Mozillaｮ Firefoxｮ バージョン 3.5 以降
• Google Chrome™ の最新の安定バージョン
• Microsoft® Internet Explorer® バージョン 7 以降
497
第 26 章 Salesforce コンソールインテグレーションツールキット
Salesforce コンソールページへの URL は、ブラウザに貼り付けたり、ブックマークから
選択したりした場合に機能しないことがあります。既知の問題については、Salesforce
ヘルプの「Salesforce コンソールの制限」を参照してください。
サポート対象の Salesforce のエディション
Salesforce コンソールインテグレーションツールキットは、次の Salesforce エディション
(Service Cloud 付属) で使用できます。
• Developer Edition
• Enterprise Edition
• Unlimited Edition
• Performance Edition
既存のSalesforceのお客様が上記のいずれかのエディションにアップグレードする場合
は、担当者にご連絡ください。
クイックスタート
Salesforce コンソールインテグレーションツールキットの使用を開始するには、まず
JavaScript を使用してツールキットに接続します。
使用を開始するには、次の手順に従います。
1. ツールキットに接続します。
2. ツールキットで非同期コールを実行します。
3. Force.com Canvas を使用して Salesforce コンソールを、認証方式が必要な外部アプ
リケーションと統合します。
Salesforce コンソールインテグレーションツールキットを使用して、Salesforce コンソー
ルで次の処理を実行します。
• 指定した URL を表示する新しい主タブまたはサブタブを開く
• 主タブまたはサブタブのタイトルを設定する
• 主タブまたはサブタブの ID を返す
• 指定した主タブまたはサブタブを閉じる
498
第 26 章 Salesforce コンソールインテグレーションツールキット
ツールキットへの接続
Salesforce コンソールインテグレーションツールキットを使用する JavaScript コードの冒
頭部分では、ツールキットを JavaScript コードで使用できるようにする必要がありま
す。このための構文は、JavaScript を Visualforce ページとサードパーティドメインのどち
らに埋め込んでいるかによって異なります。
• Visualforce ページ、またはカスタム onclick JavaScript ボタン以外のソースの場合、
ツールキットファイルを参照する <script> タグを指定します。
<apex:page>
<script src="/support/console/33.0/integration.js"
type="text/javascript"></script>
...
</apex:page>
Visualforce の場合、integration.js は相対パスに追加すれば十分であり、この方
法をお勧めします。
• サードパーティドメインの場合:
<script
src="https://c.na1.visual.force.com/support/console/33.0/integration.js"
type="text/javascript"></script>
サードパーティドメインの場合、ツールキットを使用するには integration.js
への絶対 URL を指定する必要があります。ツールキットライブラリにアクセスでき
るデフォルトのインスタンスは、
c.na1.visual.force.com/support/console/33.0/integration.js です。
組織のインスタンスを判別できない場合は、デフォルトのインスタンスを使用す
ることをお勧めします。
Salesforce コンソールインテグレーションツールキットのバージョンは URL に含まれま
す。
499
第 26 章 Salesforce コンソールインテグレーションツールキット
Salesforce コンソールインテグレーションツールキッ
トを使用した非同期コール
Salesforce コンソールインテグレーションツールキットを使用すると、非同期コールを
発行できます。非同期コールにより、クライアント側のプロセスは、サーバからの
コールバックを待機せずに処理を続行できます。非同期コールを発行するには、コー
ルバック関数と呼ばれる API コールに追加のパラメータを設定する必要があります。
結果の準備ができると、サーバは結果を指定してコールバックメソッドを呼び出しま
す。
非同期の構文:
method('arg1','arg2', ..., callback_method);
次に例を示します。
//Open a new primary tab with the Salesforce home page in it
sforce.console.openPrimaryTab(null, 'http://www.salesforce.com',
false, 'Salesforce', callback);
Force.com Canvas の使用
署名付き要求や OAuth 2.0 プロトコルなどの認証方式を必要とする外部アプリケーショ
ンに Salesforce コンソールを統合するには、Force.com Canvas を使用することをお勧めし
ます。
Force.com Canvas と Salesforce コンソールインテグレーションツールキットは似ていま
す。これらはツールと JavaScript API のセットで、開発者がサードパーティシステムを
Salesforce に追加するために使用できます。ただし、Force.com Canvas の利点の 1 つとし
て、認証方式を選択できるという点があります。詳細は、『Force.com Canvas 開発者ガ
イド』を参照してください。
メモ: キャンバスアプリケーションをコンソールに表示するには、コンソールに
カスタムコンソールコンポーネントとして追加する必要があります。Salesforce ヘ
ルプの 「カスタムコンソールコンポーネントの追加」を参照してください。
500
第 26 章 Salesforce コンソールインテグレーションツールキット
キャンバスアプリケーションの開発時にSalesforce コンソールインテグレーションツー
ルキットの機能を含めるには、次の操作を実行します。
1. コンソールインテグレーションツールキット API を index.jsp に含めます。
2. ドメインのホワイトリストがコンソールにある場合は、キャンバスアプリケー
ションのドメインをホワイトリストに追加します。Salesforce ヘルプの「Salesforce
コンソールのホワイトリストのドメイン」を参照してください。
3. Sfdc.canvas.client.signedrequest() をコールし、コンソールインテグ
レーションツールキット API に必要な署名付き要求を保存します。たとえば、
Force.com Canvas の認証方式が署名付き要求の場合は、次を実行します。
Sfdc.canvas.client.signedrequest('<%=signedRequest%>')
Force.com Canvas の認証方式が OAuth の場合は、『Force.com Canvas 開発者ガイド』
の「キャンバスアプリケーションでのコンテキストの取得」に記載されている
ように、コンテキストの取得に使用されるコールバック関数で次を実行しま
す。
Sfdc.canvas.client.signedrequest(msg)
Salesforce コンソールインテグレーションツールキットおよびキャンバスアプリケー
ションを使用する場合は、次の点を考慮してください。
• コンソールインテグレーションツールキット API スクリプトは署名付き要求によっ
て異なるため、Sfdc.canvas.client.signedrequest() コールの実行後に追加
する必要があります。スクリプトを動的に読み込むことをお勧めします。
• キャンバスのサイドバーコンポーネントに関連付けられているレコードのエンティ
ティ ID を取得するには、次を実行します。
// Get signedRequest
var signedRequest = Sfdc.canvas.client.signedrequest();
var parsedRequest = JSON.parse(signedRequest);
// get the entity Id that is associated with this canvas sidebar
component.
var entityId = parsedRequest.context.environment.parameters.entityId;
501
第 26 章 Salesforce コンソールインテグレーションツールキット
• OAuth の entityId を取得するには、次を実行します。
var entityId = msg.payload.environment.parameters.entityId;
msg.payload の取得方法の例については、『Force.com Canvas 開発者ガイド』の
「キャンバスアプリケーションでのコンテキストの取得」を参照してください。
ベストプラクティス
• Salesforce コンソールインテグレーションツールキットに含まれるメソッドの多くは
非同期で、コールバックメソッドを使用して結果を返すため、各メソッドのドキュ
メントを参照してそれぞれの応答の情報を理解することをお勧めします。
• Salesforce コンソールインテグレーションツールキットで生成されるエラーは通常、
JavaScript 処理を停止しない方法で発行されます。そのため、コードをデバッグしや
すいように、Firebug for Firefox のようなツールを使用して JavaScript コンソールを監視
することをお勧めします。
• Salesforce コンソールで Visualforce ページを適切に表示するには、次のように設定す
ることをお勧めします。
– デフォルト設定 showHeader="true" を受け入れ、apex:page タグの
sidebar="false" を設定します。
– サイドバーやヘッダーのない既存のウィンドウに表示するには、ツールキット
のメソッドが含まれるカスタムボタンやリンクの [動作] を設定する。詳細は、
Salesforce オンラインヘルプの「カスタムボタンとリンクの定義」を参照してく
ださい。
• Firefox を使用する場合、有効なアラートボックスのあるタブで closeTab() をコー
ルしないことをお勧めします。ブラウザで正しく読み込まれない可能性がありま
す。
• ユーザが無効な URL でメソッドを開始すると、重複したタブが開く可能性がありま
す。メソッドに URL を挿入する前に、有効性を確認することをお勧めします。
• 「外部ページ」がタブ名として表示されないように、openPrimaryTab() や
openSubtab() などのメソッドに tabLabel 引数を指定することをお勧めしま
す。
502
第 26 章 Salesforce コンソールインテグレーションツールキット
• Visualforce を使用して Salesforce コンソールのサイドバーをカスタマイズ、拡張、ま
たは統合する方法についての詳細は、Salesforceオンラインヘルプの「カスタムコン
ソールコンポーネントの概要」を参照することをお勧めします。
• サードパーティドメインのツールキットを有効化するには、Salesforce コンソールの
ホワイトリストにそのドメインを追加する必要があります。Salesforceオンラインヘ
ルプの「Salesforce コンソールのホワイトリストのドメイン」を参照してください。
Salesforce コンソールインテグレーションツールキッ
トを使用したサンプル Visualforce ページ
この例では、Salesforce コンソールインテグレーションツールキットを使用して、Salesforce
コンソールのユーザインターフェースを変更する方法を示します。
1. Visualforce ページを作成します。『Visualforce 開発者ガイド』を参照してくださ
い。
2. 次のサンプルコードを切り取って Visualforce ページに貼り付けます。
このコードは、Salesforce コンソールインテグレーションツールキットの各種関
数を示しています。
<apex:page standardController="Case">
<apex:includeScript
value="/support/console/20.0/integration.js"/>
<script type="text/javascript">
function openPrimaryTab() {
sforce.console.openPrimaryTab(undefined,
'http://www.salesforce.com', true, 'salesforce');
}
503
第 26 章 Salesforce コンソールインテグレーションツールキット
//The callback function that openSubtab will call once
it's got the ID for its primary tab
var callOpenSubtab=function callOpenSubtab(result) {
sforce.console.openSubtab(result.id,
'http://www.yahoo.com', true, 'yahoo');
};
function openSubtab() {
sforce.console.getEnclosingPrimaryTabId(callOpenSubtab);
}
//Sets the title of the current tab to "SFDC"
function setTitle() {
sforce.console.setTabTitle('SFDC');
}
//The callback function that closeTab will call once it's
got the ID for its tab
var callCloseTab= function callCloseTab(result) {
sforce.console.closeTab(result.id);
}
function closeTab() {
504
第 26 章 Salesforce コンソールインテグレーションツールキット
sforce.console.getEnclosingTabId(callCloseTab);
}
</script>
<A HREF="#" onClick="openPrimaryTab();return false">Open A
Primary Tab</A>
<p/><A HREF="#" onClick="openSubtab();return false">Open A
Subtab</A>
<p/><A HREF="#" onClick="setTitle();return false">Set Title
to SFDC</A>
<p/><A HREF="#" onClick="closeTab();return false">Close This
Tab</A>
</apex:page>
メモ: この例は、ケース上のカスタムリンクをクリックすると実行されるように
設定されています。詳細は、Salesforceオンラインヘルプの「カスタムボタンとリ
ンクの定義」を参照してください。
上記の Visualforce ページを作成して、カスタムリンクとしてケースに追加します。そ
の後、ケースに移動してリンクをクリックすると、次のページが表示されます。
505
第 26 章 Salesforce コンソールインテグレーションツールキット
サンプル Visualforce ページの出力
メソッド
次のメソッドを使用して、Salesforce コンソールの操作性をカスタマイズします。
このガイドでは、Salesforce コンソールインテグレーションツールキットで使用可能な
メソッドの概要について説明します。コールと応答についての詳細は、『Salesforce コ
ンソールインテグレーションツールキット開発者ガイド』を参照してください。
次の要素についてメソッドを使用できます。
• 主タブとサブタブ
• コンピュータテレフォニーインテグレーション (CTI)
• アプリケーションレベルのカスタムコンソールコンポーネント
• 転送通知
• Live Agent
主タブとサブタブ用のメソッド
Salesforce コンソールには、Salesforce ページが主タブまたはサブタブとして表示されま
す。主タブには、取引先など、作業する主な項目が表示されます。サブタブには、取
引先の取引先責任者や商談など、関連項目が表示されます。
コンソールの主タブまたはサブタブには、次のメソッドを使用できます。
506
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
closeTab()
指定された主タブまたはサブタブを閉じ
ます。主タブの最初のタブを閉じると、
主タブそのものが閉じるので注意してく
ださい。このメソッドは、APIバージョン
20.0 以降でのみ使用できます。
focusPrimaryTabById()
指定された ID を使用して、ブラウザです
でに開いている主タブにフォーカスを移
動します。このメソッドは、APIバージョ
ン 22.0 以降でのみ使用できます。
focusPrimaryTabByName()
指定された名前を使用して、ブラウザで
すでに開いている主タブにフォーカスを
移動します。このメソッドは、API バー
ジョン 22.0 以降でのみ使用できます。
focusSubtabById()
指定された ID を使用して、ブラウザです
でに開いているサブタブにフォーカスを
移動します。このメソッドは、API バー
ジョン 22.0 以降でのみ使用できます。
focusSubtabByNameAndPrimaryTabId() 指定された名前と主タブ ID を使用して、
ブラウザですでに開いているサブタブに
フォーカスを移動します。このメソッド
は、API バージョン 22.0 以降でのみ使用で
きます。
focusSubtabByNameAndPrimaryTabName() 指定された名前と主タブ名を使用して、
ブラウザですでに開いているサブタブに
フォーカスを移動します。このメソッド
は、API バージョン 22.0 以降でのみ使用で
きます。
Salesforce コンソールのタブ、または関連
タブのグループへの URL を生成します。
外部 URL を含むタブがある場合、正しく
表示できるようにコンソールのホワイト
generateConsoleUrl()
507
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
リストにその外部 URL を追加します。詳
細は、オンラインヘルプの「Salesforce コ
ンソールのホワイトリストのドメイン」
を参照してください。このメソッドは、
API バージョン 28.0 以降でのみ使用できま
す。
getEnclosingPrimaryTabId()
現在の主タブの ID を返します。このメ
ソッドは主タブまたはサブタブ内で機能
します。ナビゲーションタブやカスタム
コンソールコンポーネント内では機能し
ません。このメソッドは、APIバージョン
20.0 以降でのみ使用できます。
getEnclosingPrimaryTabObjectId() サブタブを含む、現在の主タブのオブジェ
クト ID を返します。たとえば、ケース ID
や取引先 ID などです。このメソッドは、
主タブまたはサブタブ内で機能します。
このメソッドは、API バージョン 24.0 以降
でのみ使用できます。
getEnclosingTabId()
主タブまたはサブタブである可能性のあ
る、現在の Visualforce ページを含むタブの
ID を返します。このメソッドは、サブタ
ブで囲まれたコンポーネントからコール
が行われる場合に機能します。このメソッ
ドは、API バージョン 20.0 以降でのみ使用
できます。
getFocusedPrimaryTabId()
ブラウザがフォーカスされている主タブ
の ID を返します。このメソッドは、API
バージョン 25.0 以降でのみ使用できます。
getFocusedPrimaryTabObjectId()
ブラウザがフォーカスされている主タブ
のオブジェクト ID を返します。このメ
508
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
ソッドは、API バージョン 25.0 以降でのみ
使用できます。
getFocusedSubtabId()
ブラウザがフォーカスされているサブタ
ブの ID を返します。たとえば、ケース ID
や取引先 ID などです。このメソッドは、
API バージョン 25.0 以降でのみ使用できま
す。
getFocusedSubtabObjectId()
ブラウザがフォーカスされているサブタ
ブのオブジェクト ID を返します。たとえ
ば、ケース ID や取引先 ID などです。この
メソッドは、API バージョン 24.0 以降での
み使用できます。
getPageInfo()
指定されたタブのページ情報の内容をロー
ドした後、その情報を返します。タブ ID
が null の場合、囲んでいる主タブまたは
サブタブのページ情報を返します。カス
タムコンソールコンポーネントからペー
ジ情報を取得するには、tabId が最初の
パラメータとしてこのメソッドに渡され
る必要があります。このメソッドは、API
バージョン 26.0 以降でのみ使用できます。
getPrimaryTabIds()
開いている主タブのすべての ID を返しま
す。このメソッドは、API バージョン 26.0
以降でのみ使用できます。
getSubtabIds()
主タブ ID によって指定された主タブ上に
あるサブタブのすべての ID を返します。
主タブ ID が null の場合、現在の主タブ上
にあるサブタブの ID を返します。このメ
ソッドは、カスタムコンソールコンポー
ネント、または Visualforce ページによって
上書きされた詳細ページからのみコール
509
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
できます。このメソッドは、APIバージョ
ン 26.0 以降でのみ使用できます。
getTabLink()
Salesforce コンソールのタブ、または関連
タブのグループへの URL を取得します。
このメソッドは、API バージョン 28.0 以降
でのみ使用できます。
isInConsole()
ページが Salesforce コンソールにあるかど
うかを判断します。このメソッドは、API
バージョン 22.0 以降でのみ使用できます。
onEnclosingTabRefresh()
囲んでいるタブが更新されるとコールさ
れる関数を登録します。このメソッドは、
API バージョン 24.0 以降でのみ使用できま
す。
onFocusedSubtab()
ブラウザのフォーカスが異なるサブタブ
に変更されるとコールされる関数を登録
します。このメソッドは、APIバージョン
24.0 以降でのみ使用できます。
onTabSave()
ユーザがサブタブの [保存されていない変
更] ダイアログボックスの [保存] をクリッ
クすると、コールバックメソッドを登録
し、コールします。このメソッドを使用
する場合、コールバックメソッドで
setTabUnsavedChanges() をコールす
る必要があります。これにより、カスタ
ム保存操作が完了したことがコンソール
に通知されます。
setTabUnsavedChanges() へのコール
では、保存が成功したことを示すには、
最初のパラメータとして false を渡し、
保存が失敗したことを示すには、true を
510
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
渡します。このメソッドは、APIバージョ
ン 28.0 以降でのみ使用できます。
generateConsoleUrl() メソッドで作
openConsoleUrl()
成した URL (Salesforce コンソールのタブ、
または関連タブのグループへの URL) を開
きます。このメソッドは、APIバージョン
28.0 以降でのみ使用できます。
openPrimaryTab()
指定された URL (相対または絶対) のコンテ
ンツを表示する新しい主タブを開きます。
また、既存のタブを上書きすることもで
きます。このメソッドは、APIバージョン
20.0 以降でのみ使用できます。
openSubtab()
指定された URL (相対または絶対) のコンテ
ンツを表示する新しいサブタブ (主タブ内)
を開きます。また、既存のサブタブを上
書きすることもできます。主タブの ID を
使用して主タブで新しいサブタブを開く
場合に使用します。このメソッドは、API
バージョン 20.0 以降でのみ使用できます。
openSubtabByPrimaryTabName()
指定された URL (相対または絶対) のコンテ
ンツを表示する新しいサブタブ (主タブ内)
を開きます。また、既存のサブタブを上
書きすることもできます。主タブの名前
を使用して主タブで新しいサブタブを開
く場合に使用します。このメソッドは、
API バージョン 22.0 以降でのみ使用できま
す。
refreshPrimaryTabById()
サブタブを含む、ID で指定された主タブ
を更新します。このメソッドでは、外部
ページまたは Visualforce ページへの URL を
持つサブタブは更新できません。このメ
511
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
ソッドは、API バージョン 22.0 以降でのみ
使用できます。
refreshPrimaryTabByName()
サブタブを含む、名前で指定された主タ
ブを更新します。このメソッドでは、外
部ページまたは Visualforce ページへの URL
を持つサブタブは更新できません。この
メソッドは、API バージョン 22.0 以降での
み使用できます。
refreshSubtabById()
指定された ID で最後に確認された URL を
持つサブタブを更新します。最後に確認
された URL が外部ページまたは Visualforce
ページの場合、このメソッドではサブタ
ブを更新できません。このメソッドは、
API バージョン 22.0 以降でのみ使用できま
す。
refreshSubtabByNameAndPrimaryTabId() 指定された名前と主タブ ID で最後に確認
された URL を持つサブタブを更新します。
最後に確認された URL が外部ページまた
は Visualforce ページの場合、このメソッド
ではサブタブを更新できません。このメ
ソッドは、API バージョン 22.0 以降でのみ
使用できます。
refreshSubtabByNameAndPrimaryTabName() 指定された名前と主タブ名で最後に確認
された URL を持つサブタブを更新します。
最後に確認された URL が外部ページまた
は Visualforce ページの場合、このメソッド
ではサブタブを更新できません。このメ
ソッドは、API バージョン 22.0 以降でのみ
使用できます。
resetSessionTimeOut()
Visualforce ページのセッションタイムアウ
トをリセットします。これにより、ユー
512
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
ザがログアウトせず操作を続行できます。
詳細は、Salesforce ヘルプの 「セッション
セキュリティの設定」を参照してくださ
い。このメソッドは、API バージョン 24.0
以降でのみ使用できます。
setTabLink()
コンソールタブの URL 属性をタブのコン
テンツの場所に設定します。ユーザが
Salesforce ドメインの外にあるコンテンツ
を表示したタブに移動するときは、この
メソッドを使用して安全なコンソール URL
を生成します。このメソッドは、APIバー
ジョン 28.0 以降でのみ使用できます。
setTabIcon()
指定されたタブにアイコンを設定します。
タブが指定されていない場合、アイコン
は囲んでいるタブに設定されます。この
メソッドを使って、タブのアイコンをカ
スタマイズします。このメソッドは、API
バージョン 28.0 以降でのみ使用できます。
setTabStyle()
指定のタブにカスケードスタイルシート
(CSS) を設定します。タブが指定されてい
ない場合、CSS は囲んでいるタブに設定さ
れます。このメソッドを使って、タブの
デザインをカスタマイズします。このメ
ソッドは、API バージョン 28.0 以降でのみ
使用できます。
setTabTextStyle()
指定されたタブのテキストにカスケード
スタイルシート (CSS) を設定します。タブ
が指定されていない場合、CSS は囲んでい
るタブのテキストに設定されます。この
メソッドを使って、タブのテキストスタ
イルをカスタマイズします。このメソッ
513
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
ドは、API バージョン 28.0 以降でのみ使用
できます。
setTabTitle()
主タブまたはサブタブのタイトルを設定
します。このメソッドは、APIバージョン
20.0 以降でのみ使用できます。
setTabUnsavedChanges()
未保存のデータを示すため、サブタブの
保存されていない変更アイコン ( ) を設
定します。このメソッドは、APIバージョ
ン 23.0 以降でのみ使用できます。
コンピュータテレフォニーインテグレーション (CTI)
のメソッド
Salesforce コールセンターは、Salesforce とコンピュータテレフォニーインテグレーショ
ンシステムをシームレスに統合します。開発者が Open CTI と CTI Toolkit のどちらを使用
して CTI システムを作成しても、コンソールユーザは、ソフトフォン (コンソールの
フッターに表示される通話制御ツール) でテレフォニー機能にアクセスできます。詳
細は、Salesforce ヘルプの「Salesforce Open CTI の概要」および「コールセンターの概要」
を参照してください。
コンソールで、CTI システムに次のメソッドを使用できます。
メソッド
説明
fireOnCallBegin()
コールが開始したことを通知するイベントを
起動します。相互関係ログとカスタムコン
ソールコンポーネント間で情報を送受信する
ために使用されます。このメソッドは、API
バージョン 31.0 以降でのみ使用できます。
fireOnCallEnd()
コールが終了したことを通知するイベントを
起動します。相互関係ログとカスタムコン
ソールコンポーネント間で情報を送受信する
514
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
ために使用されます。このメソッドは、API
バージョン 31.0 以降でのみ使用できます。
fireOnCallLogSaved()
onCallLogSaved() に登録された
eventHandler をコールします。相互関係
ログとカスタムコンソールコンポーネント間
で情報を送受信するために使用されます。こ
のメソッドは、API バージョン 31.0 以降での
み使用できます。
getCallAttachedData()
コールオブジェクト ID、または有効なコール
がない場合は null によって表されるコールの
添付データを返します。このデータは、JSON
形式で返されます。このメソッドは、コン
ピュータテレフォニーインテグレーション
(CTI) 用です。これは、API バージョン 24.0 以降
でのみ使用できます。
getCallObjectIds()
有効なコールオブジェクト ID を到着順に返す
か、有効なコールがない場合は null を返しま
す。このメソッドは、コンピュータテレフォ
ニーインテグレーション (CTI) 用です。これ
は、API バージョン 24.0 以降でのみ使用でき
ます。
onCallBegin()
コールが開始 (着信) するとコールされる関数
を登録します。このメソッドは、コンピュー
タテレフォニーインテグレーション (CTI) 用で
す。これは、API バージョン 24.0 以降でのみ
使用できます。
onCallEnd()
コールが終了するとコールされる関数を登録
します。このメソッドは、コンピュータテレ
フォニーインテグレーション (CTI) 用です。こ
れは、API バージョン 24.0 以降でのみ使用で
きます。
515
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
onCallLogSaved()
相互関係ログが活動ログを保存すると起動さ
れる関数を登録します。相互関係ログとカス
タムコンソールコンポーネント間で情報を送
受信するために使用されます。このメソッド
は、API バージョン 31.0 以降でのみ使用でき
ます。
onSendCTIMessage()
メッセージが sendCTIMessage() で送信さ
れると起動される関数を登録します。相互関
係ログとカスタムコンソールコンポーネント
間で情報を送受信するために使用されます。
このメソッドは、API バージョン 31.0 以降で
のみ使用できます。
sendCTIMessage()
メッセージを CTI アダプタまたは Open CTI に
送信します。このメソッドは、コンピュータ
テレフォニーインテグレーション (CTI) 用で
す。これは、API バージョン 24.0 以降でのみ
使用できます。
setCallAttachedData()
コールオブジェクト ID に関連付けられたコー
ルデータを設定します。相互関係ログとカス
タムコンソールコンポーネント間で情報を送
受信するために使用されます。このメソッド
は、API バージョン 31.0 以降でのみ使用でき
ます。
setCallObjectIds()
コールオブジェクト ID を到着の昇順で設定し
ます。このメソッドは、API バージョン 31.0
以降でのみ使用できます。
516
第 26 章 Salesforce コンソールインテグレーションツールキット
アプリケーションレベルのカスタムコンソールコン
ポーネント用のメソッド
カスタムコンソールコンポーネントを使用すると、Visualforce、キャンバスアプリケー
ション、参照項目、または関連リストを使用してSalesforce コンソールのフッター、サ
イドバー、強調表示パネル、および相互関係ログをカスタマイズ、拡張、または統合
することができます。システム管理者は、次のいずれかにコンポーネントを追加でき
ます。
• 特定のページにコンテンツを表示するページレイアウト
• すべてのページとタブにコンテンツを表示するSalesforce コンソールアプリケーショ
ン
詳細は、Salesforce ヘルプの「カスタムコンソールコンポーネントの概要」を参照して
ください。
すべてのページとタブにコンテンツを表示するコンポーネント (アプリケーションレ
ベルのコンソールと呼ばれる) には、次のメソッドを使用できます 。
メソッド
説明
addToBrowserTitleQueue()
3 秒ごとに回転するタイトルリストにブラ
ウザタブタイトルを追加します。このメ
ソッドは、API バージョン 28.0 以降でのみ
使用できます。
blinkCustomConsoleComponentButtonText() ページ上のアプリケーションレベルのカ
スタムコンソールコンポーネントでボタ
ンのテキストを点滅させます。このメソッ
ドは、API バージョン 25.0 以降でのみ使用
できます。
isCustomConsoleComponentHidden() アプリケーションレベルのカスタムコン
ソールコンポーネントのウィンドウが非
表示かどうかを判断します。このメソッ
ドは API バージョン 32.0 以降で使用できま
す。API バージョン 31.0 以前では、このメ
ソッドは
517
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
isCustomConsoleComponentWindowHidden()
という名前でした。
isCustomConsoleComponentPoppedOut() カスタムコンソールコンポーネントがブ
ラウザでポップアウトしているかどうか
を判別します。このメソッドを使用する
には、マルチモニターコンポーネントが
有効になっている必要があります。詳細
は、オンラインヘルプの「Salesforce コン
ソールのマルチモニターコンポーネント
の設定」を参照してください。このメソッ
ドは、API バージョン 30.0 以降でのみ使用
できます。
isCustomConsoleComponentWindowHidden() アプリケーションレベルのカスタムコン
ソールコンポーネントのウィンドウが非
表示かどうかを判断します。このメソッ
ドは、API バージョン 25.0 から 31.0 で使用
できます。
isInCustomConsoleComponent()
ページがアプリケーションレベルのカス
タムコンソールコンポーネントにあるか
どうかを判断します。このメソッドは、
API バージョン 25.0 以降でのみ使用できま
す。
onCustomConsoleComponentButtonClicked() アプリケーションレベルのカスタムコン
ソールコンポーネントでボタンをクリッ
クするとコールされる関数を登録します。
このメソッドは、API バージョン 25.0 以降
でのみ使用できます。
onFocusedPrimaryTab()
ブラウザのフォーカスが異なる主タブに
変更されるとコールされる関数を登録し
ます。このメソッドは、API バージョン
25.0 以降でのみ使用できます。
518
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
removeFromBrowserTitleQueue()
3 秒ごとに回転するタイトルのリストから
ブラウザタブタイトルを削除します。こ
のメソッドは、API バージョン 28.0 以降で
のみ使用できます。
scrollCustomConsoleComponentButtonText() ページに表示されるアプリケーションレ
ベルのカスタムコンソールコンポーネン
トで、ボタンのテキストをスクロールし
ます。このメソッドは、API バージョン
25.0 以降でのみ使用できます。
setCustomConsoleComponentButtonIconUrl() ページに表示されるアプリケーションレ
ベルのカスタムコンソールコンポーネン
トの、ボタンアイコン URL を設定します。
このメソッドは、API バージョン 25.0 以降
でのみ使用できます。
setCustomConsoleComponentButtonStyle() ページに表示されるアプリケーションレ
ベルのカスタムコンソールコンポーネン
トを起動するために使用する、ボタンの
スタイルを設定します。このメソッドは、
API バージョン 25.0 以降でのみ使用できま
す。
setCustomConsoleComponentButtonText() ページに表示されるアプリケーションレ
ベルのカスタムコンソールコンポーネン
トを起動するために使用する、ボタンの
テキストを設定します。このメソッドは、
API バージョン 25.0 以降でのみ使用できま
す。
setCustomConsoleComponentHeight() ページに表示されるアプリケーションレ
ベルのカスタムコンソールコンポーネン
トのウィンドウの高さを設定します。こ
のメソッドは API バージョン 32.0 以降で使
用できます。
519
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
setCustomConsoleComponentPopoutable() カスタムコンソールコンポーネントがブ
ラウザでポップアウトまたはポップイン
するように設定します。このメソッドを
使用するには、マルチモニターコンポー
ネントが有効になっている必要がありま
す。詳細は、オンラインヘルプの
「Salesforce コンソールのマルチモニター
コンポーネントの設定」を参照してくだ
さい。このメソッドは、API バージョン
30.0 以降でのみ使用できます。
setCustomConsoleComponentVisible() ページに表示されるアプリケーションレ
ベルのカスタムコンソールコンポーネン
トのウィンドウ表示を設定します。この
メソッドは API バージョン 32.0 以降で使用
できます。API バージョン 31.0 以前では、
このメソッドは
setCustomConsoleComponentWindowVisible()
という名前でした。
setCustomConsoleComponentWidth() ページに表示されるアプリケーションレ
ベルのカスタムコンソールコンポーネン
トのウィンドウの幅を設定します。この
メソッドは API バージョン 32.0 以降で使用
できます。
setCustomConsoleComponentWindowVisible() ページに表示されるアプリケーションレ
ベルのカスタムコンソールコンポーネン
トのウィンドウ表示を設定します。この
メソッドは、API バージョン 31.0 以前での
み使用できます。
setSidebarVisible()
tabId と領域に基づいてコンソールのサ
イドバーを表示または非表示にします。
このメソッドは API バージョン 33.0 以降で
使用できます。
520
第 26 章 Salesforce コンソールインテグレーションツールキット
転送通知用のメソッド
転送通知とは、Salesforce コンソールのリストおよび詳細ページにあるビジュアルイン
ジケータであり、ユーザのセッション中にレコードまたは項目が変更されると表示さ
れます。たとえば、2 つのサポートエージェントが同じケースで作業している場合に
一方のエージェントが [優先度] を変更すると、もう一方のエージェントに転送通知
が表示されるため、そのエージェントは変更を認識でき、同じ作業を行わなくてすみ
ます。
システム管理者は、Salesforce コンソールを設定するときに、転送通知が表示されるタ
イミング、および転送通知機能をトリガするオブジェクトと項目を選択します。開発
者は、転送通知メソッドを使用して、Salesforce で提供されるデフォルトのビジュアル
インジケータの範囲を超えて転送通知をカスタマイズできます。たとえば、開発者は
以下で示すメソッドを使用して、特定のコンソールユーザがアクセスできるオブジェ
クトに関するカスタムの通知を作成できるため、メール通知を排除できます。詳細
は、Salesforce ヘルプの「Salesforce コンソールでの転送通知の設定」を参照してくださ
い。
転送通知メソッドを使用するときは、次の点を考慮してください。
• 転送通知のリスナー応答は、コンソールの転送通知をトリガするために選択され
たオブジェクトと項目にのみ使用できます。
• addPushNotificationListener() メソッドで追加されたリスナーが Visualforce
ページに含まれている場合は、ページで通知を受信します。リスナーは、コンソー
ルの転送通知をトリガするために選択されたオブジェクトをユーザが更新し、変
更後のレコードに現在のユーザがアクセスできる場合に通知を受信します。この
機能は、Salesforceユーザインターフェースで設定される転送通知と次の点で異なり
ます。
– リスナーは、すべてのユーザが加えた変更について更新通知を受信します。
– リスナーは、オブジェクトの項目が転送通知をトリガするために選択されてい
なくても更新または作成され、さらに、変更内容の詳細が通知に含まれていな
い場合に通知を受信します。たとえば、Case オブジェクトの Status が転送通
知をトリガするよう設定されていても、Case オブジェクトで Priority が変更
された場合、リスナーはケースが変更されたことを示す通知 (詳細は含まれな
い) を受信します。
– リスナーは、Salesforce コンソールの [リストの更新方法を選択] および [詳細ペー
ジの更新方法を選択] 転送通知の設定には従いません。
521
第 26 章 Salesforce コンソールインテグレーションツールキット
– 通知の受信停止は、removePushNotificationListener() メソッドを使用
してリスナーを削除することによってのみ可能です。
コンソールでの転送通知には、次のメソッドを使用できます。
メソッド
説明
addPushNotificationListener() 転送通知用のリスナーを追加します。ユーザ
がリスナーを登録できるのは 1 回のみです。
ただし、ユーザがリスナーを削除するか、別
のユーザによってリスナーが削除されると、
再びリスナーを登録できます。このメソッド
は、API バージョン 26.0 以降でのみ使用でき
ます。転送通知についての詳細は、「転送通
知用のメソッド」 (ページ521)を参照してくだ
さい。
removePushNotificationListener() 転送通知用に追加されたリスナーを削除しま
す。このメソッドは、API バージョン 26.0 以
降でのみ使用できます。転送通知についての
詳細は、「転送通知用のメソッド」 (ページ
521)を参照してください。
Live Agent のメソッド
Live Agent により、Web ベースのチャットを使用して顧客または Web サイトの訪問者と
リアルタイムに接続できます。詳細は、Salesforce ヘルプの「Salesforce コンソールへの
Live Agent の追加」を参照してください。
Salesforce Console for Service の Live Agent には、次のメソッドを使用できます。
メソッド
説明
acceptChat()
チャット要求を受け入れます。API バージョ
ン 29.0 以降で使用できます。
declineChat()
チャット要求を却下します。API バージョン
29.0 以降で使用できます。
522
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
endChat()
エージェントが現在参加しているチャットを
終了します。API バージョン 29.0 以降で使用で
きます。
getAgentInput()
特定のチャットキーを持つチャットのチャッ
トログにある、エージェントのテキスト入力
領域に現在あるテキストの文字列を返しま
す。API バージョン 29.0 以降で使用できます。
getAgentState()
オンライン、退席中、またはオフラインな
ど、エージェントの現在の Live Agent 状況を返
します。API バージョン 29.0 以降で使用できま
す。
getChatLog()
特定のチャットキーに関連付けられたチャッ
トのチャットログを返します。API バージョ
ン 29.0 以降で使用できます。
getChatRequests()
エージェントに割り当てられたチャット要求
のチャットキーを返します。API バージョン
29.0 以降で使用できます。
getDetailsByChatKey()
特定のチャットキーに関連付けられたチャッ
トの詳細を返します。API バージョン 29.0 以降
で使用できます。
getDetailsByPrimaryTabId()
特定の主タブ ID に関連付けられたチャットの
詳細を返します。API バージョン 29.0 以降で使
用できます。
getEngagedChats()
エージェントが現在参加しているチャットの
チャットキーを返します。API バージョン 29.0
以降で使用できます。
getMaxCapacity()
エージェントの割り当て済みエージェント設
定に指定されているとおりに、現在のエー
ジェントの最大可能チャット数を返します。
API バージョン 29.0 以降で使用できます。
523
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
onAgentSend()
エージェントが Salesforce コンソールでチャッ
トメッセージを送信するとコールされる関数
を登録します。このメソッドにより、メッ
セージが受信されます。また、このメソッド
はメッセージがチャット訪問者に送信される
前に発生します。API バージョン 29.0 以降で使
用できます。
onAgentStateChanged()
オンラインから退席中への変更など、エー
ジェントが Live Agent 状況を変更するとコール
される関数を登録します。API バージョン 29.0
以降で使用できます。
onChatCanceled()
チャット訪問者がチャット要求をキャンセル
するとコールされる関数を登録します。API
バージョン 29.0 以降で使用できます。
onChatCriticalWaitState()
チャットへの応答が不可欠になるか、待機中
のチャットが応答されるとコールされる関数
を登録します。API バージョン 29.0 以降で使用
できます。
onChatDeclined()
エージェントがチャット要求を却下すると
コールされる関数を登録します。API バージョ
ン 29.0 以降で使用できます。
onChatEnded()
参加していたチャットが終了するとコールさ
れる関数を登録します。API バージョン 29.0 以
降で使用できます。
onChatRequested()
エージェントがチャット要求を受け取ると
コールされる関数を登録します。API バージョ
ン 29.0 以降で使用できます。
onChatStarted()
エージェントが顧客と新しいチャットを開始
するとコールされる関数を登録します。API
バージョン 29.0 以降で使用できます。
524
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
onChatTransferredOut()
参加していたチャットが別のエージェントに
転送されるとコールされる関数を登録しま
す。API バージョン 29.0 以降で使用できます。
onCurrentCapacityChanged()
エージェントが受け入れ可能なチャット数が
変わるとコールされる関数を登録します。た
とえば、エージェントが新しいチャットを受
け入れて現在参加しているチャットを終了し
たり、割り当てられているチャットの数が変
わったり、チャット要求がチャットキューに
入れられたりする場合です。API バージョン
29.0 以降で使用できます。
onCustomEvent()
チャット中にカスタムイベントが実行される
とコールされる関数を登録します。API バー
ジョン 29.0 以降で使用できます。
onNewMessage()
顧客、エージェント、またはスーパーバイザ
から新しいメッセージが送信されるとコール
される関数を登録します。API バージョン 29.0
以降で使用できます。
onTypingUpdate()
チャットウィンドウの顧客のテキストが変更
されるとコールされる関数を登録します。プ
レビューが有効になっている場合、この関数
は、顧客がチャットウィンドウのテキストを
編集するたびにコールされます。プレビュー
が有効になっていない場合、この関数は、顧
客がチャットウィンドウで入力を開始または
停止するたびにコールされます。API バージョ
ン 29.0 以降で使用できます。
sendCustomEvent()
特定のチャットキーを持つチャットのクライ
アント側のチャットウィンドウにカスタムイ
ベントを送信します。API バージョン 29.0 以降
で使用できます。
525
第 26 章 Salesforce コンソールインテグレーションツールキット
メソッド
説明
sendMessage()
特定のチャットキーを持つチャットに、エー
ジェントから新しいチャットメッセージを送
信します。API バージョン 29.0 以降で使用でき
ます。
setAgentInput()
特定のチャットキーを持つチャットのチャッ
トログにある、エージェントのテキスト入力
領域にあるテキストの文字列を設定します。
API バージョン 29.0 以降で使用できます。
setAgentState()
オンライン、退席中、またはオフラインな
ど、エージェントの Live Agent 状況を設定しま
す。API バージョン 29.0 以降で使用できます。
リソース
Salesforce コンソールインテグレーションキットに関する次のリソースについては、
Salesforce 開発者のネットワーク (http://developer.salesforce.com/docs) を検索
してください。
• Salesforce コンソールインテグレーションツールキット開発者ガイド
• Salesforce ヘルプの「Salesforce コンソールの概要」
526
第 27 章
Open CTI
Open CTIを使用すると、高度なスキルを持つシステム管理者と開発者は、CTI (コンピュー
タテレフォニーインテグレーション) システムを開発してサードパーティの CTI システ
ムを Salesforce と統合できます。そうすることで、Salesforce ユーザが CTI アダプタをマ
シンにインストールしなくてもソフトフォンを使用できるようになります。
Salesforce CRM Call Center は、Salesforce とサードパーティのコンピュータテレフォニーイ
ンテグレーション (CTI) システムを融合します。Open CTI が導入される前は、Salesforce
ユーザは、CTI アダプタプログラムをコンピュータにインストールしなければ、CTI シ
ステムの機能を使用できませんでした。また、そのようなプログラムにはメンテナン
スが必要なデスクトップソフトウェアが含まれていたため、クラウドアーキテクチャ
の本来の利点が生かされていないことが多くありました。Open CTI では、開発者は次
のことを実行できます。
• CTI アダプタを使用せずに Salesforce と統合する CTI システムを構築する。
• Salesforce および Salesforce コンソールと完全に統合されたパーツとして機能するカ
スタマイズ可能なソフトフォン (通話管理ツール) を作成する。
• Mac、Linux、または Windows マシン上の Microsoft® Internet Explorer®、Mozilla® Firefox®、
Apple® Safari®、または Google Chrome™ 向けの CTI などブラウザおよびプラットフォー
ムにとらわれない CTI システムを提供する。
Open CTI は、ブラウザベースの JavaScript API です。Open CTI は、ソフトフォンを表示す
るためのクライアントとしてブラウザを使用します。バージョンは、各リリースの API
バージョンと一致します。たとえば、SOAP APIの現在のバージョンが 28.0 の場合、Open
CTI もバージョン 28.0 が使用されます。
このガイドでは、Open CTI と使用可能な API メソッドの使用方法の概要について説明し
ます。詳細は、『Open CTI 開発者ガイド』を参照してください。
サポートされるブラウザ
Open CTI でサポートされるブラウザの最小要件は次のとおりです。
• Mozilla® Firefox® 3.6
527
第 27 章 Open CTI
• Google Chrome™ 7
• Microsoft® Internet Explorer® 8
• Apple® Safari® 4
サポート対象の Salesforce のエディション
Open CTI は、次の Salesforce エディションで使用可能です。
• Developer Edition
• Professional Edition
• Enterprise Edition
• Unlimited Edition
• Performance Edition
既存のSalesforceのお客様が上記のいずれかのエディションにアップグレードする場合
は、担当者にご連絡ください。
クイックスタート
Open CTI の使用を開始するには、まず JavaScript を使用して Open CTI に接続します。
使用を開始するには、次の手順に従います。
1. ツールキットに接続します。
2. Open CTI で非同期コールを実行します。
3. Force.com Canvas を使用して Salesforce コンソールを、認証方式が必要な外部アプ
リケーションと統合します。
Open CTI を使用して Salesforce で次の操作を実行します。
• ソフトフォンの高さまたは幅を設定する
• クリック-to-ダイヤルを有効化または無効化する
• コールセンター定義ファイルの設定を返す
• ユーザが Salesforce コンソールを表示しているかどうかを判別する
• Salesforce コンソールでソフトフォンを表示または非表示にする
• ページに関する情報を返す
528
第 27 章 Open CTI
• Salesforce で公開されている Apex クラスから Apex メソッドを実行する
• Salesforce のオブジェクトを保存または更新する
• Salesforceでキーワードを検索し、ソフトフォンレイアウトの定義に従って一致する
レコードを画面ポップする
Open CTI への接続
Open CTI を使用する JavaScript コードの冒頭部分では、ツールキットを JavaScript コード
で使用できるようにする必要があります。このための構文は、JavaScript を Visualforce
ページとサードパーティドメインのどちらに埋め込んでいるかによって異なります。
• Visualforce ページ、またはカスタム onclick JavaScript ボタン以外のソースの場合、
Open CTI ファイルを参照する <script> タグを指定します。
<apex:page>
<script src="/support/api/33.0/interaction.js"
type="text/javascript"></script>
...
</apex:page>
Visualforce の場合、integration.js は相対パスに追加すれば十分であり、この方
法をお勧めします。
• サードパーティドメインの場合:
<script
src="https://c.na1.visual.force.com/support/api/33.0/interaction.js"
type="text/javascript"></script>
サードパーティドメインの場合、ツールキットを使用するには interaction.js
への絶対 URL を指定する必要があります。ツールキットライブラリにアクセスでき
るデフォルトのインスタンスは、
https://c.na1.visual.force.com/support/api/33.0/interaction.js で
す。組織のインスタンスを判別できない場合は、デフォルトのインスタンスを使
用することをお勧めします。
Open CTI のバージョンは、URL に含まれています。
529
第 27 章 Open CTI
Open CTI での非同期コール
Open CTI を使用すると、非同期コールを発行できます。非同期コールにより、クライ
アント側のプロセスは、サーバからのコールバックを待機せずに処理を続行できま
す。非同期コールを発行するには、API コールに、コールバック関数と呼ばれる追加
のパラメータを設定する必要があります。結果の準備ができると、サーバは結果を指
定してコールバックメソッドを呼び出します。
非同期の構文:
method('arg1','arg2', ..., callback_method);
次に例を示します。
//Set SoftPhone height
sforce.interaction.cti.setSoftphoneHeight(300, callback);
メモ: コールの結果は、実行コンテキストによって異なります。たとえば、標準
の Salesforce アプリケーションで setSoftphoneWidth() をコールしても影響は
ありませんが、Salesforce コンソールで setSoftphoneWidth() をコールすると
ソフトフォンの幅がサイズ変更されます。
Force.com Canvas の使用
署名付き要求や OAuth 2.0 プロトコルなどの認証方式を必要とする外部アプリケーショ
ンに Open CTI を統合するには、Force.com Canvas を使用することをお勧めします。
Force.com Canvas と Open CTI は似ています。これらはツールと JavaScript API のセットで、
開発者がサードパーティシステムを Salesforce に追加するために使用できます。ただ
し、Force.com Canvasの利点の 1 つとして、認証方式を選択できるという点があります。
詳細は、『Force.com Canvas 開発者ガイド』を参照してください。
メモ: キャンバスアプリケーションを Salesforce コンソールに表示するには、コン
ソールにカスタムコンソールコンポーネントとしてそれを追加する必要がありま
す。Salesforce ヘルプの「カスタムコンソールコンポーネントの追加」を参照して
ください。
キャンバスアプリケーションの開発時に Open CTI の機能を含めるには、次の操作を実
行します。
530
第 27 章 Open CTI
1. index.jsp に Open CTI API を含めます。
2. Sfdc.canvas.client.signedrequest() をコールし、コンソールインテグ
レーションツールキット API に必要な署名付き要求を保存します。たとえば、
Force.com Canvas の認証方式が署名付き要求の場合は、次を実行します。
Sfdc.canvas.client.signedrequest('<%=signedRequest%>')
Force.com Canvas の認証方式が OAuth の場合は、『Force.com Canvas 開発者ガイド』
の「キャンバスアプリケーションでのコンテキストの取得」に記載されている
ように、コンテキストの取得に使用されるコールバック関数で次を実行しま
す。
Sfdc.canvas.client.signedrequest(msg)
Open CTI およびキャンバスアプリケーションを使用する場合は、次の点を考慮してく
ださい。
• Open CTI API スクリプトは署名付き要求によって異なるため、
Sfdc.canvas.client.signedrequest() へのコールの実行後に追加する必要が
あります。スクリプトを動的に読み込むことをお勧めします。
• キャンバスのサイドバーコンポーネントに関連付けられているレコードのエンティ
ティ ID を取得するには、次を実行します。
// Get signedRequest
var signedRequest = Sfdc.canvas.client.signedrequest();
var parsedRequest = JSON.parse(signedRequest);
// get the entity Id that is associated with this canvas sidebar
component.
var entityId = parsedRequest.context.environment.parameters.entityId;
• OAuth の entityId を取得するには、次を実行します。
var entityId = msg.payload.environment.parameters.entityId;
msg.payload の取得方法の例については、『Force.com Canvas 開発者ガイド』の
「キャンバスアプリケーションでのコンテキストの取得」を参照してください。
531
第 27 章 Open CTI
ベストプラクティス
• Open CTI に含まれるメソッドの多くは非同期で、コールバックメソッドを使用して
結果を返すため、各メソッドのドキュメントを参照してそれぞれの応答の情報を
理解することをお勧めします。
• Open CTI で生成されるエラーは通常、JavaScript 処理を停止しない方法で発行されま
す。そのため、コードをデバッグしやすいように、Firebug for Firefox のようなツール
を使用して JavaScript コンソールを監視することをお勧めします。
• Visualforce を使用して Salesforce コンソールのサイドバーをカスタマイズ、拡張、ま
たは統合する方法についての詳細は、Salesforceオンラインヘルプの「カスタムコン
ソールコンポーネントの概要」を参照してください。
コールセンター定義ファイル
コールセンター定義ファイルは、特定のソフトフォン向けの、Salesforce でコールセン
ターの定義に使用される一連の項目と値を指定します。Salesforce では、Salesforce CRM
Call Centerと複数の CTI システム業者とのインテグレーションをサポートするためにコー
ルセンター定義ファイルを使用します。
Salesforce CRM Call Center のコールセンターには、ソフトフォンで特に動作するコールセ
ンター定義ファイルが必要です。Open CTIでカスタムソフトフォンを開発する場合は、
それをサポートするコールセンター定義ファイルを記述する必要があります。特定の
ソフトフォンに対するコールセンターの最初のインスタンスは、Salesforce にアダプタ
のコールセンター定義ファイルをインポートすることで定義する必要があります。そ
の後のコールセンターは、最初のインポートで作成された元のコールセンターをコ
ピーすることで作成できます。
組織でソフトフォンを変更したり、新規ソフトフォンを開発したりする場合は、元の
ソフトフォンのコールセンター定義ファイルをカスタマイズして、追加のコールセン
ターに必要な情報を含めるようにする必要があります。たとえば、バックアップサー
バをサポートするシステムに対してソフトフォンを開発している場合、コールセン
ター定義ファイルにはそのバックアップサーバの IP アドレスとポート番号を含める必
要があります。バックアップサーバを使用しないシステムのソフトフォンに関連付け
られているコールセンター定義ファイルには、これらの項目は必要ありません。
テキストエディタまたは XML エディタを使用して、次のトピックで示すガイドライン
に従ってコールセンター定義ファイルを定義します。
532
第 27 章 Open CTI
メモ: Salesforce CRM Call Center の設定や、コールセンター定義ファイルのインポー
トおよびコピーについての詳細は、Salesforce オンラインヘルプの「Salesforce CRM
Call Center の設定」と「コールセンターの作成」を参照してください。
コールセンター定義ファイルの XML 形式
コールセンター定義ファイルは、callCenter、section、item という 3 つの XML 要
素で構成されます。次に、各要素のプロパティと属性ついて詳しく説明します。
callCenter
この要素は、1 つのコールセンターの電話システムの定義を表します。すべての
コールセンター定義ファイルには、少なくとも 1 つの <callCenter> 要素を含め
る必要があります。<callCenter> 要素は、1 つ以上の <section> 要素で構成さ
れます。
section
この要素は、サーバ情報や発信番号など、関連するデータ項目のグルーピングを
表します。Salesforceでコールセンターを編集すると、割り当てられたセクションご
とに項目が整理されます。<section> 要素は、1 つの <callCenter> 要素に属
し、1 つ以上の <item> 要素で構成されます。
属性:
名前
型
sortOrder 正の整数
必須項目
説明
必須
Salesforce でコールセンターを編集すると
きにセクションが表示される順序。たと
えば、sortOrder="1" と指定されたセク
ションは、sortOrder="2" と指定された
セクションの直前に表示されます。
sortOrder の値は、負でない整数である
必要があり、1 つのコールセンター定義内
で数値をスキップすることはできません。
たとえば、1 つのコールセンター定義ファ
イルに 3 つの <section> 要素がある場
合、1 つの <section> 要素は
sortOrder="0"、1 つの <section> 要
素は sortOrder="1"、1 つの要素は
533
第 27 章 Open CTI
名前
型
必須項目
説明
<section> 要素は sortOrder="2" を持
つ必要があります。
name
String
必須
Salesforce データベースで定義される、セ
クションの内部名。この値を使用して、
カスタムアダプタまたはソフトフォンコー
ドの作成時にセクションを参照できます。
名前には、空白や他の句読点を含まない
英数字のみを使用する必要があります。
それぞれの名前は 40 文字以内に制限され
ています。
req で始まる名前は、必須の Salesforce セ
クションのみのために予約されています
(Salesforce ヘルプの 「コールセンターの必
須要素と必須属性」を参照)。name 属性
に使用できない他の予約語として、
label、sortOrder、
internalNameLabel、
displayNameLabel があります。
label
String
省略可能
Salesforceで表示するときのセクション名。
表示ラベルには、UTF-8 文字で構成された
任意の文字列を使用できます。それぞれ
の名前は 1000 文字以内に制限されていま
す。
item
この要素は、プライマリサーバの IP アドレスや国際電話の発信番号など、1 つの
コールセンター定義の 1 つの項目を表します。Salesforceでコールセンターを編集す
ると、各 <item> 要素は、それが属するセクションの下に表示されます。1 つの
<item> 要素に、複数の <section> 要素を指定できます。
属性:
534
第 27 章 Open CTI
名前
型
sortOrder 正の整数
必須項目
説明
必須
Salesforce でコールセンターを編集すると
きに項目が表示される順序。たとえば、
sortOrder="1" と指定された項目は、
sortOrder="2" と指定された項目の直前
に表示されます。
sortOrder の値は、負でない整数である
必要があり、1 つのコールセンター定義内
で数値をスキップすることはできません。
たとえば、1 つのコールセンター定義ファ
イルに 3 つの <item> 要素がある場合、1
つの <item> 要素は sortOrder="0"、1
つの <item> 要素は sortOrder="1"、1
つの要素は <item> 要素は
sortOrder="2" を持つ必要があります。
name
String
必須
Salesforce データベースで定義される、項
目の内部名。この値を使用して、カスタ
ムアダプタまたはソフトフォンコードの
作成時に項目を参照できます。
名前には、空白や他の句読点を含まない
英数字のみを使用する必要があります。
それぞれの名前は 40 文字以内に制限され
ています。
req で始まる名前は、必須の Salesforce セ
クションのみのために予約されています
(Salesforce ヘルプの 「コールセンターの必
須要素と必須属性」を参照)。name 属性
に使用できない他の予約語として、
label、sortOrder、
internalNameLabel、
displayNameLabel があります。
535
第 27 章 Open CTI
名前
型
必須項目
説明
label
String
省略可能
Salesforce で表示するときの項目名。表示
ラベルには、UTF-8 文字で構成された任意
の文字列を使用できます。それぞれの名
前は 1,000 文字以内に制限されています。
コールセンターの必須要素と必須属性
すべてのコール定義ファイルには、次の名前の <item> 要素を含む <section> が 1
つ必要です。
<item> 名
説明
reqInternalName データベースでコールセンターを識別する一意の識別子を表し
ます。sortOrder 値は 0 でなければならず、この値をコール
センター定義で指定する必要があります。reqInternalName
の値には、空白や他の句読点を含まない 40 文字以内の英数字の
みを使用できます。英字で始まり、組織で定義された他のすべ
てのコールセンターの reqInternalName で一意である必要が
あります。
reqDisplayName
Salesforce に表示されるコールセンターの名前を表します。
sortOrder の値は 1 である必要があります。reqDisplayName
の値は、最大長 1,000 文字の UTF-8 文字です。
reqAdapterUrl
CTI アダプタまたはソフトフォンをホストする場所を表します。
たとえば、http://localhost:11000 などです。:
/apex/softphone などの相対 URL は、Visualforce ページで有効
です。また、Force.com Canvas アプリケーションを Open CTI に追
加すると、そのアプリケーションを reqAdapterUrl より優先
させることができます (指定されている場合)。
reqUseApi
コールセンターでOpen CTIを使用しているか (true)、否か (false)
を表します。
reqSoftphoneHeight Salesforce に表示されるソフトフォンの高さ (ピクセル単位) を表
します。
536
第 27 章 Open CTI
<item> 名
説明
reqSoftphoneWidth Salesforce に表示されるソフトフォンの幅 (ピクセル単位) を表し
ます。
reqCanvasNamespace コールセンターに追加される Force.com Canvas アプリケーション
に関連付けられている名前空間を表します。キャンバスアプリ
ケーションを Open CTI に追加する場合は、必須です。
reqCanvasApiName コールセンターに追加される Force.com Canvas アプリケーション
に関連付けられている API 名を表します。キャンバスアプリケー
ションを Open CTI に追加する場合は、必須です。
必要に応じて、このセクションに追加の <item> 要素を指定できます。
コールセンターの省略可能な要素と属性
コール定義ファイルの必須要素に加え、省略可能な要素を追加してソフトフォンを設
定できます。
<item> 名
説明
reqStandbyUrl
セカンダリソフトフォンをホストする場所を表します。
スタンバイソフトフォンは、プライマリソフトフォン
のタイムアウト期間が経過し、必要なタイムアウト期
間内に notifyInitializationComplete() メソッド
がコールされていない場合に使用されます。スタンバ
イ URL を指定する場合は、reqTimeout 項目も指定す
る必要があります。
reqTimeout
スタンバイ URL を使用してソフトフォンをホストする
ための経過時間 (ミリ秒単位) を表します。タイムアウ
ト期間が経過するまでは、ソフトフォンが初期化中で
あることを示す読み込み中アイコンがソフトフォンに
表示されます。必要なタイムアウトを指定する場合は、
reqStandbyUrl 項目も指定する必要があります。
537
第 27 章 Open CTI
<item> 名
説明
reqSoftphoneWidth
Salesforce に表示されるソフトフォンの幅 (ピクセル単位)
を表します。
コールセンター定義ファイルのサンプル
次の XML コードは、コールセンター定義ファイルのサンプルを構成します。
<!-All sections and items whose name value begins with "req" are
required in a valid call center definition file. The sortOrder
and label attributes can be changed for all required sections
and items except reqGeneralInfo, reqInternalName, and
reqDisplayName, in which only the label attribute can be altered.
Note that the value for the reqInternalName item is limited to
40 alphanumeric characters and must start with an alphabetic
character. reqInternalName must be unique for all call centers
that you define.
-->
<callCenter>
<section sortOrder="0" name="reqGeneralInfo" label="General
Information">
<item sortOrder="0" name="reqInternalName"
label="InternalNameAAA">DemoAdapter</item>
538
第 27 章 Open CTI
<item sortOrder="1" name="reqDisplayName" label="Display Name">Demo
Call Center Adapter</item>
<item sortOrder="2" name="reqAdapterUrl" label="CTI Adapter
URL">https://c.force.com/softphone</item>
<item sortOrder="3" name="reqUseApi" label="Use CTI API">true</item>
<item sortOrder="4" name="reqSoftphoneHeight" label="Softphone
Height">300</item>
<item sortOrder="5" name="reqSoftphoneWidth" label="Softphone
Width">500</item>
<item sortOrder="6" name="reqCanvasNamespace" label="Canvas
Namespace">mm</item>
<item sortOrder="7" name="reqCanvasApiName" label="Canvas API
Name">Hello_World</item>
</section>
<section sortOrder="1" name="reqDialingOptions" label="Dialing
Options">
<item sortOrder="0" name="reqOutsidePrefix" label="Outside
Prefix">9</item>
<item sortOrder="1" name="reqLongDistPrefix" label="Long Distance
Prefix">1</item>
<item sortOrder="2" name="reqInternationalPrefix"
label="International Prefix">01</item>
</section>
</callCenter>
メソッド
次のメソッドを使用して、Salesforce の CTI 操作をカスタマイズします。
539
第 27 章 Open CTI
このガイドでは、Open CTI で使用可能なメソッドの概要について説明します。コール
と応答についての詳細は、『Open CTI 開発者ガイド』を参照してください。
メソッドは次の目的に使用できます。
• Salesforce アプリケーション操作
• コンピュータテレフォニーインテグレーション (CTI)
Salesforce アプリケーション操作用のメソッド
Open CTI を使用すると、CTI システムから Salesforce アプリケーションを操作できます。
次のメソッドを使用して、CTI システムと Salesforce 間、または [ケースフィード] ページ
の要素間での操作を設定できます。
CTI メソッド
メソッド
説明
getPageInfo()
現在のページに関する情報を JSON 文字列として返しま
す。
isInConsole()
ソフトフォンが Salesforce コンソールにあるかどうかを
示します。詳細は、Salesforce オンラインヘルプの
「Salesforce コンソールの概要」を参照してください。
isVisible()
ソフトフォンが表示される場合は true、非表示の場
合は false を返します。
notifyInitializationComplete() Salesforceに、ソフトフォンの初期化が完了したことと、
Salesforce がスタンバイ URL に切り替えないようにする
ことを通知します。ソフトフォンの初期化中は、[ソフ
トフォン] 領域に読み込み中アイコンが表示されます。
onFocus()
ブラウザのフォーカスが変更されるとコールされる関
数を登録します。Salesforce コンソールでは、主タブま
たはナビゲーションタブでユーザが移動すると、ブラ
ウザのフォーカスが変更されます。
refreshPage()
ページ更新が呼び出された場合は true、それ以外の
場合は false を返します。このメソッドが Salesforce
540
第 27 章 Open CTI
CTI メソッド
コンソール内でコールされると、現在の有効なタブが
更新されます。
refreshRelatedList()
指定された listName を持つ関連リストが更新された
場合は true、それ以外の場合は false を返します。
このメソッドが Salesforce コンソール内でコールされる
と、現在フォーカスのあるビューで指定のリスト名を
持つ関連リストのみが更新されます。
runApex()
Salesforce で公開された Apex クラスから Apex メソッドを
実行します。
saveLog()
オブジェクトを Salesforce で保存または更新します。
screenPop()
対象 URL (相対である必要がある) にポップします。
searchAndGetScreenPopUrl() 特定の文字列に対してソフトフォンレイアウトで指定
されたオブジェクトを検索します。検索結果と、ポッ
プ画面への相対 URL を返します。このメソッドは、実
際の画面ポップを実行しません。このメソッドは、ソ
フトフォンレイアウトで定義された画面ポップ設定を
優先します。詳細は、Salesforceオンラインヘルプの「カ
スタムソフトフォンレイアウトの設計」を参照してく
ださい。
searchAndScreenPop()
特定の文字列に対してソフトフォンレイアウトで指定
されたオブジェクトを検索します。検索結果を返し、
一致するレコードが画面にポップされます。このメ
ソッドは、ソフトフォンレイアウトで定義された画面
ポップ設定を優先します。
setVisible()
Salesforce コンソールで、ソフトフォンを表示するか非
表示にします。詳細は、Salesforce オンラインヘルプの
「Salesforce コンソールの概要」を参照してください。
ケースフィードメソッド
541
第 27 章 Open CTI
CTI メソッド
onObjectUpdate()
ケース項目、ケースフィード、またはケース関連のリ
ストデータが [ケースフィード] ページで変更されると
コールされる関数を登録します。
refreshObject()
ケース項目、ケースフィード、またはケース関連のリ
ストデータが変更されたことを [ケースフィード] ペー
ジに通知し、これらをページで強制的に更新します。
コンピュータテレフォニーインテグレーション (CTI)
のメソッド
Open CTI を使用すると、CTI システムを Salesforce に統合できます。CTI についての詳細
は、Salesforce オンラインヘルプの「コールセンターの概要」を参照してください。
次のメソッドを使用して、CTI システムを Salesforce に統合します。
メソッド
説明
disableClickToDial() クリック-to-ダイヤルを無効にします。
enableClickToDial()
クリック-to-ダイヤルを有効にします。
getCallCenterSettings() コールセンター定義ファイル内のコールセンターの設定
を JSON 文字列として返します。
getDirectoryNumbers() コールセンターのディレクトリから電話番号のリストを
返します。
getSoftphoneLayout() ソフトフォンレイアウトを JSON 文字列として返します。
ソフトフォンレイアウトについての詳細は、Salesforce オ
ンラインヘルプの「カスタムソフトフォンレイアウトの
設計」を参照してください。
onClickToDial()
有効化された電話番号をユーザがクリックするとコール
される関数を登録します。
setSoftphoneHeight() ソフトフォンの高さ (ピクセル単位) を設定します。
542
第 27 章 Open CTI
メソッド
説明
setSoftphoneWidth()
Salesforce コンソールのソフトフォンの幅 (ピクセル単位)
を設定します。詳細は、Salesforce オンラインヘルプの
「Salesforce コンソールの概要」を参照してください。
リソース
Open CTI に関する次のリソースについては、Salesforce 開発者のネットワーク
(http://developer.salesforce.com/docs) を検索してください。
• Open CTI 開発者ガイド
• Salesforce ヘルプの「Salesforce Open CTI の概要」
• Salesforce ヘルプの「ソフトフォンの概要」
• Salesforce ヘルプの「コールセンターの概要」
543

エンジンオイル価格表

ACSESバーコード出荷管理支援システム

大規模情報系システムにおける統合ID管理システム構築（362KB）

書籍関連サイトと連携した研究室規模の 蔵書管理システムにおける登録

マイナー曲の推薦アプリケーションの提案

F1生まれのエンジンオイル - PETRONAS(ペトロナス)

こ ちら