Account Engagement APIを利用する

公開日: 2024.11.21

この記事で学べること
はじめに
設定方法
Account Engagement API利用に関する注意点
参考
まとめ

この記事で学べること

Account Engagement APIを利用する方法
Account Engagement API利用に関する注意点

はじめに

本記事では、Account Engagement APIを利用する方法についてご紹介します。

まず、Account Engagement APIを使用するためには、Account Engagementへのアクセス権を持つSSO対応済みのSalesforceユーザーにより、Salesforceのユーザー認証を成功させる必要があります。

Salesforceのユーザー認証が完了すると、アクセストークンが発行されますので、そのアクセストークンを利用してAccount Engagement APIを実行します。

事前に必要な設定内容、実際にAccount Engagement APIを実行する方法について、以下に手順をご紹介します。

※APIの呼び出し元となるプログラムの実装については開発範囲となるため、具体的な実装方法や開発物のトラブルシューティングに関してはサポート対象外となります。

設定方法

1. 接続アプリケーションの作成手順

Account Engagement APIを使用する事前準備として、SalesforceユーザーによるOAuth認証を行うために、Account Engagement API用の「接続アプリケーション」の設定を作成します。

設定手順は以下のステップになります。

1. Salesforceの画面右上の[設定]をクリックします。

2.クイック検索で「アプリケーションマネージャー」と検索し、[アプリケーションマネージャー]メニューを開きます。

3.[新規接続アプリケーション]ボタンをクリックします。

4.接続アプリケーション名・API参照名・連絡先のメールアドレスを設定します。

5.APIセクションで[OAuth 設定の有効化]にチェックを入れます。

6.[コールバック URL]を設定します。

たとえば、のようなURLを設定しますが、ブラウザーベースの認証フローを使用しない場合、入力されたURLは使用されません。

7.[選択した OAuth 範囲]セクションで、[Pardot サービスを管理（pardot_api）]を選択して[追加]します。

リフレッシュトークンの使用など、より複雑なシナリオとなる場合は、他のスコープも選択します。
※[サポートされる認証フローに Proof Key for Code Exchange (PKCE) 拡張を要求]が有効な場合は、認証の際にcode_challengeパラメータが必要となります。
上記対応が特に必要ではない場合は、[サポートされる認証フローに Proof Key for Code Exchange (PKCE) 拡張を要求]を無効にしてお試しください。

8.設定を保存します。

2. OAuth認証実行に必要な情報の取得

SalesforceユーザーによるOAuth認証を実行する際に必要となる以下の情報を取得します。

コンシューマー鍵
コンシューマーの秘密
Account EngagementビジネスユニットID
Salesforceユーザーのログイン情報

＜コンシューマー鍵とコンシューマーの秘密の確認手順＞

1.Salesforceの画面右上の[設定]をクリックします。

2.クイック検索で「アプリケーションマネージャー」と検索し、[アプリケーションマネージャー]メニューを開きます。

3.先程作成したAPI用の接続アプリケーションの行へ移動し、右端の逆三角アイコンより[参照]を選択します。

4.API (OAuth 設定の有効化)セクションの[コンシューマーの詳細を管理]ボタンをクリックします。

5.[コンシューマー鍵]の値をコピーして記録します。

6.[コンシューマーの秘密]の値をコピーして記録します。

＜Account Engagement ビジネスユニットIDの確認手順＞

1.Salesforceの画面右上の[マーケティング設定]をクリックします。

2.クイック検索で[ビジネスユニット]と検索し、[ビジネスユニット設定]メニューを選択します。

3.APIを利用するAccount Engagementアカウントの[ビジネスユニットID]の値をコピーします。

＜Salesforceのログイン認証を実行するユーザーの確認＞

1.Account Engagement Lightning Appを使用してAccount Engagementにアクセスできるユーザー、または「Salesforceでログイン」を使用してpi.pardot.comにログインできるユーザーを用意します。

2.1のユーザーについて、Salesforceへのログイン情報を確認します。

3. Salesforce OAuth認証の実行

ステップ2で取得した情報を元にSalesforceユーザーの認証を行い、アクセストークンを取得します。

以下のステップでは、参考までにAPI開発ツールの「Postman」を利用してサンプルをご紹介します。

POST URL：
grant_type：password
client_id：＜コンシューマー鍵＞
client_secret：＜コンシューマーの秘密＞
username：＜SalesforceユーザーのUsername＞
password：＜Salesforceユーザーのパスワード＞

4. Account Engagement APIの実行

OAuth認証に成功すると、レスポンスとしてアクセストークンの値が返却されます。

そのアクセストークンの値を[Authorization]ヘッダに設定し、併せてAccount EngagementビジネスユニットIDの値を[Pardot-Business-Unit-Id ]ヘッダにそれぞれ設定することで、Account Engagement APIの実行が可能となります。

※[Authorization]の設定値としては、「Bearer」と「アクセストークンの値」の間に半角スペースが必要であり、

「Bearer xxxxxxxxxxx」のような形式となります。

こちらは、API バージョン5のVisitor Activity Queryを実行した際のイメージ画面となります。

※参考ドキュメント

Account Engagement API利用に関する注意点

APIの呼び出し元となるプログラムでは、APIドキュメントに定義されているエラーコードを考慮したハンドリングが必要です。
APIバージョンの違いについて

API バージョン 3

[1 つのメールアドレスに対して複数のプロスペクトを有効化]が無効であり、同一のメールアドレスを持つプロスペクトの複数作成が許可されていないアカウントの場合、バージョン3をご利用ください。

API バージョン 4

[1 つのメールアドレスに対して複数のプロスペクトを有効化]が有効であり、同一のメールアドレスを持つプロスペクトを複数作成できるアカウントの場合、バージョン4をご利用ください。

API バージョン 5

バージョン5では、利用対象のオブジェクトやオブジェクトに対する操作が追加されており、[1 つのメールアドレスに対して複数のプロスペクトを有効化]が有効になっているかどうかに関わらず、ご利用いただけます。

ご契約のAccount Engagementエディション毎にAPIの日次コール制限数が設けられている点にご注意ください。
リリース情報に関しましては、最新のリリースノートや開発者ドキュメントをご確認ください。

参考

Account Engagement API Quick Start（開発者ドキュメント）
Marketing Cloud Account Engagement API: クイックルック（Trailhead）

まとめ

本記事では、Account Engagement APIを利用する方法を解説しました。

運用方法や他社事例などについては、質問広場～初心者から上級者まで～日本グループまたは Account Engagement(旧Pardot) 日本グループにてご質問ください。

便利な使い方