Marketing Cloud Engagement 全体で REST API を使用する

学習の目的

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

Marketing Cloud Engagement REST API の使い方を説明する。
REST API とやりとりする Marketing Cloud Engagement アプリケーションを特定する。

REST の説明

Marketing Cloud Engagement の REST API により、Marketing Cloud Engagement の最新機能にアクセスすることができます。この単元では、REST API を使用して達成できる内容と、各自のニーズに合わせて REST API をカスタマイズする方法を詳しく説明します。

REST API の基本

詳しい説明に入る前に、REST API のさまざまな要求やエンドポイントに共通する特徴から見ていきましょう。

REST API はマルチチャネルでの使用をサポートし、JSON 要求ボディを受け入れます。
要求はすべて同期し、最大 4 MB の情報を保持できます。
トラッキング情報をはじめとするデータ取得操作は、300 秒後にタイムアウトします。
その他の要求は 120 秒後にタイムアウトします。

上記の点を念頭に、Marketing Cloud Engagement の数種類のアプリケーションに対して REST API でどのようなことを達成できるか見ていきましょう。

Content Builder

Marketing Cloud Engagement の Content Builder は、メール、プッシュ、SMS などのメッセージに記載するマーケティング資料を作成できるところです。アカウントから情報がどのような方法で送信されるかに関係なく、コンテンツ (アセットともいう) はすべて Content Builder 内に存在します。コンテンツの作成や整理に使用するテンプレートやスロットもアセットです。

Content Builder では、アセットやカテゴリ (フォルダーともいう) を取得、更新、削除する REST API 要求のほか、さほど一般的でない他の要求も処理できます。「Salesforce 開発者」に、Content Builder とやりとりする際に使用する要求のサンプルやリソースなどの完全リストが記載されています。

例: メールメッセージの更新

次の要求のリソースと構造を見てください。この例は既存のメールメッセージを更新するもので、一般的な JSON ペイロードも示しています。この要求は、指定したルートに対する PATCH メソッドを使用して、メールメッセージのコンテンツを更新します。ID 値が、アカウントにあるアセットの識別に使用する外部キーを受け入れます。

PATCH /asset/v1/content/assets/{id}
{
 "name": "NTO Welcome Series Email",
 "channels": {
   "email": true,
   "web": false
},
 "views": {
   "html": {
     "content": "<!DOCTYPE html><body>This is a simple message.</body></html>"
 },
 "text": {},
 "subjectline": {},
 "preheader": {}
 }
}

Journey Builder

Journey Builder は、連絡先がイベントや動作に基づいて各種のメッセージをどのように受信するかを決定します。たとえば、ニュースレターに登録したが、リンクをクリックしたり商品を購入したことが一度もない顧客に対してメールメッセージを送信することが考えられます。これはジャーニーの一例です。Marketing Cloud Engagement でジャーニーを作成するには、次のような手順に従います。

Marketing Cloud Engagement で送信可能データエクステンションを作成します。このデータエクステンションには、各連絡先の一意の連絡先キーと、送信の一部として使用する情報が含まれます。
Marketing Cloud Engagement でイベント定義を作成します。こうしたイベント定義で、どの連絡先がいつジャーニーにエントリするかを管理します。
ジャーニーを構築します。ジャーニーには、連絡先がどのメッセージを受信するかを決定するアクティビティ (送信や更新など) が設定されます。またここで、ジャーニーが成功したかどうかを判断するための目標も追加できます。
ジャーニーを公開します。このステップで、ジャーニーを有効にし、連絡先を評価してジャーニーにエントリするかどうかを判断します。
エントリイベントを起動します。このステップから、エントリ条件を満たした連絡先のジャーニーが始まります。

ジャーニーにはかなり複雑な操作が含まれることがあるため、「Salesforce 開発者」にこうした全手順の詳しい参照ドキュメントが掲載されています。

例: Journey Builder からのメールメッセージの送信

参考のために、簡単な例を見てみましょう。以下は、メールメッセージを送信するイベントの JSON です。この情報は、アクティビティと、メタデータが関連付けられたトリガーによる送信を指定します。ジャーニーの過程でイベントがトリガーされると、メールが送信されます。

{
   "type": "EMAILV2",
   "key": "<activity key>",
   "name": "<activity name>",
   "applicationId": "<Marketing Cloud Engagement provided GUID>",
   "outcomes": [
      {
        "key": "<outcome key>",
        "next": "<key of next activity>"
      }
   ],
   "metaData":{
      "icon":"/img/email-icon.svg",
      "iconSmall":"/img/email-icon.svg",
      "category":"message",
      "version":"1.0",
      "isConfigured":true
   },
   "configurationArguments":{
      "triggeredSend":{
        "emailId":"<email id>",
        "emailSubject": "<subject>",
        "preHeader":"<preheader>",
        "description":"<description>",
        "campaigns":[
            {
               "id":"<campaign id>",
               "name":"<campaign name>",
               "color":"<campaign color>"
            }
   ],
   "sendClassificationId":"<send classification id>",
   "senderProfileId":"<sender profile id>",
   "deliveryProfileId":"<delivery profile id>",
   "publicationListId":"<publication list id>",
   "suppressionLists":[
       {
          "name":"<suppression list name>",
          "id":"<suppression list id>"
       }
   ],
   "domainExclusions":[
       {
          "name":"<domain exclusion name>",
          "id":"<domain exclusion id>"
       }
   ],
   "exclusionFilter":"<exclusion script>",
   "isTrackingClicks":true,
   "isMultipart":true,
   "isSendLogging":true,
   "suppressTracking":true,
   "ccEmail":"<cc email>",
   "bccEmail":"<bcc email>",
   "keyword":"<keyword>",
   "throttleLimit":500,
   "throttleOpens":"12:00",
   "throttleCloses":"12:30",
   "isSalesforceTracking":true
       }
   }
}

GroupConnect

Marketing Cloud Engagement では、Facebook Messenger や LINE のようなアプリケーションからメッセージを送信する場合に GroupConnect REST API を使用します。連絡先が、発送や予約の更新、アカウントの変更などの連絡事項のメッセージを受け取るような場合です。

GroupConnect API 連携は、「Salesforce 開発者」に記載の手順に従って設定できます。

例: Facebook ページの登録

この例には、プラットフォームを識別して、必要なアクセス情報を示し、登録するページを識別するサンプルの要求が示されています。

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /ott/v1/registration
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
    "ottPlatformName" : "messenger",
    "ottPlatformAttributes" : {
       "applicationId" : "1093076390764037",
       "applicationSecret" : "03d537gg656gvkbe9b430f002e9c4517",
       "pageId" : "1732555047025799",
       "pageName" : "SFMC Engineers",
       "pageAccessToken" :
"someaccesstoken4fasdcruib213123knubkdnfisdubnu12312ub3pijnb",
       "endpointUrl" :
"https://graph.facebook.com/v2.6/me/messages",
       "callbackVerifyToken" : "this_is_the_verify_token",
       "isActive": true
    }
}

MobileConnect

MobileConnect では Marketing Cloud Engagement アカウントが SMS や MMS メッセージを連絡先に送信できます。この種のメッセージは、メールメッセージよりも細かな規制の対象となるため、MobileConnect は、送信に適用される規制に準拠できるようにする各種のオプトインメカニズムを備えています。各連絡先が、次の 3 種類のいずれかの方法でメッセージの受信を選択する必要があります。

シングルオプトイン。連絡先がショートコードを使用して、以降のコミュニケーションを購読するための SMS メッセージを送信します。
ダブルオプトイン。連絡先が SMS メッセージを送信し、その返信でメッセージの継続的な受信を希望することを確定します。
ダブルオプトインと年齢確認。上記の 2 通の確認メッセージのほか、連絡先がメッセージを受信可能な年齢に達していることを表明します。

連絡先が購読したら、個別に、またはリストを使用して、購読者にさまざまなメッセージを送信できます。また、特定のアクティビティ (購入や発送など) の後に送信する、トリガーによるメッセージも作成できます。他の一般的な API 要求として、購読確認や、オプトインプロセスの過程での Web フォーム (またはモバイルアプリケーション) の使用などが挙げられます。

例: MobileConnect からの SMS メッセージの送信

では、新しい購読者を歓迎するメッセージを送信する場合の例を見てみましょう。メッセージを送信する前に、Subscribe 値と Resubscribe 値で購読の意思を確認する必要があります。

POST
https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/sms/v1/messageContact/MzA6Nzg6MA/send
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN
{
   "mobileNumbers": [
   "13175551212"
   ],
   "Subscribe": true,
   "Resubscribe": true,
   "Override": true,
   "messageText": "Welcome to Salesforce Developers",
}

Personalization Builder

Personalization Builder は Einstein レコメンデーションと連動して、顧客のニーズ、関心、好みを基にマルチチャネルメッセージをパーソナライズします。この API 連携により、レコメンデーションの作成に使用する情報を更新したり、プライバシー要求を管理したり、大きなレポートをダウンロードすることができます。

この連携には、Marketing Cloud Engagement アカウントの Crimson Kraken API キーが必要です。このキーにアクセスできない場合は、Marketing Cloud Engagement 管理者にお問い合わせください。

例: Personalization Builder 設定の更新

次の例は、Personalization Builder の指定したプロファイルのプライバシー設定を更新するために必要な情報を示しています。

Host:  https://app.igodigital.com
POST /api/v2/organization/12345678/privacy
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
   "batch": {
      "hashed-id-01": ["do_not_track"], // Adds "do_not_track" privacy setting, removes "do_not_profile" or "do_not_process" if they were previously set
      "hashed-id-02": ["do_not_profile"], // Adds "do_not_profile" privacy setting, removes "do_not_track" or "do_not_process" if they were previously set
      "hashed-id-03": ["do_not_process"], // Adds "do_not_process" privacy setting, removes "do_not_profile" or "do_not_track" if they were previously set
      "hashed-id-04": ["do_not_track", "do_not_profile"], // Adds "do_not_track" and "do_not_profile" privacy settings, removes "do_not_process" if it was previously set
      "hashed-id-05": ["do_not_track", "do_not_process"], // Adds "do_not_track" and "do_not_process" privacy settings, removes "do_not_profile" if it was previously set
      "hashed-id-06": ["do_not_profile", "do_not_process"], // Adds "do_not_profile" and "do_not_process" privacy settings, removes "do_not_track" if it was previously set
      "hashed-id-07": ["do_not_track", "do_not_profile", "do_not_process"], // Adds "do_not_track", "do_not_profile" and "do_not_process" privacy settings
      "hashed-id-08": [], // Removes any existing privacy settings for profile
      "hashed-id-09": ["rtbf_delete"], // Deletes profile and associated data
      "hashed-id-10": ["rtbf_suppress"] // Deletes profile and associated data after suppression period
   }
}

Transactional メッセージング

Transactional メッセージング API は、注文確認、パスワードのリセット、その他の非プロモーションメッセージに使用する自動メッセージングを管理します。これらのコミュニケーションには、メールまたは SMS メッセージを使用できます。この API によって、Email Studio または MobileConnect の通常のトリガーによる送信よりもパフォーマンスが加速します。また、イベント通知サービス (即時通知 API) を使用して、送信に対する即時の確認を受け取ることができます。

この API を使用して Transactional メッセージを作成する手順は、次のとおりです。

Content Builder でメールメッセージ、Email Studio でリスト (または MobileConnect でキーワード) を作成します。
アクセストークンを取得します。
REST API 経由で Transactional 送信定義を作成します。Email Studio でトリガーによる送信、または MobileConnect でアウトバウンドメッセージを作成した場合は、Transactional REST API の送信に失敗します。
(省略可能) メッセージに関するリアルタイムのトラッキングデータを配信するイベント通知サービスを使用して、購読を作成することができます。

例: Transactional メールメッセージの送信

次のサンプルコードには、Transactional メールメッセージの送信に必要な情報の例が示されています。

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /messaging/v1/email/messages/f4fe74b7-c3c0-4e5a-9f49-b63a641109a2
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
  "definitionKey": "2FA_order_accounts",
  "recipient":
  {
   "contactKey": "recipient2",
    "to": "recipient2@example.com",
    "attributes": {
      "UserAttribute_1": "value_1",
      "UserAttribute_n": "value_n",
    }
  },
}

たくさんの内容を説明してきました! けれども、これは REST API を使ってできることの出発点にすぎません。「Salesforce 開発者」には他にもリソースが掲載されており、さらなる可能性を探求できます。次は、Email Studio と SOAP API を連携させる方法について学習します。