前書き.この記事で分かることと考慮していないこと

この記事で分かること

その1.Eloqua上でAPI経由でキャンペーンを作成する方法

Eloqua(Oracleのマーケティング業務アプリケーション)には
キャンペーンキャンバス機能があり
GUIからマーケティングキャンペーンの作成が可能です。
また、Eloquaと外部システムとの連携が必要で
外部システムからマーケティングキャンペーンを作成したい場合は
APIを経由した形でもキャンペーンを作成することができるようでした。

その2.キャンペーンAPIのエンドポイントの使い方

この記事では、私がキャンペーンAPIを使いながら
キャンペーンを介したメール配信までの検証に使用した
エンドポイントとその使い方をまとめました。

と言いますのも、Oracle EloquaのAPIに関して
公式のリファレンスがありましたが
・リクエストに含むべきミニマムの情報が分かりにくい
・必要なAPIを順次実行した際に前のAPIで設定した項目がnullでAPIが実行できなかったり
といくつかはまりポイントがあったので、ここに備忘しておきます。

この記事で考慮していないこと

その1.APIの認証プロセス

今回はエンドポイントのリクエストボディや実行結果の確認を主題にしています。
そのため、エンドポイントを実行する前の認証プロセスは割愛させていただきました。

その2.実際の業務フロー

主にAPIの呼び出しは、外部システムとの連携において行われることが多い
と想定されますが
その背景となるであろう実際の業務の流れは考慮していません。
ので、業務・外部システムとの連携フローそのものの設計は
別で実施いただく必要があると存じます。

本題.キャンペーンAPIを使う

前提

その1.できるだけ少ない設定項目で実行しています

Eloquaに限らず業務アプリのAPIは設定内容(リクエストボディ)が多くなりがちです。
さらにその設定内容は必須なものと必須でないものが混在しています。
今回の検証では、必須の項目+αを設定してエンドポイントを実行しています。
APIを介した作成物を確認の上、適宜カスタマイズください。

その2.事前に作成しておくアセットが2点あります

1つはセグメント、もう1つはEメールです。
GUI経由でもAPI経由でも構いませんので、事前にご用意ください。
Eloquaのキャンペーンは「誰に」、「何を」、「いつ」アプローチするかを
GUI上で設定ができる機能です。
その際に使用するセグメント(誰に)、Eメール(何を)については
事前に作成済しどちらもIDを取得した前提で進めます。

その3.Eメールグループの設定はお忘れなく

事前に作成済みのEメールについては
Eメールグループの設定がない場合は
キャンペーンを有効化する際にエラーが起きてしまい
キャンペーンを有効化できませんでしたのでご注意ください。

その4.キャンペーン実行までのフロー

APIを介してキャンペーンを実行する際のフローは下記になります。
それぞれでエンドポイントを実行します。

1.キャンペーンを作成する
2.キャンペーンを有効化する

有効化した際には対象のセグメントに
メールが送信される形になるためテスト用のセグメントを作成の上
セグメントにもテスト用のコンタクトを追加いただくとよいかもしれません。

エンドポイントを実行する！

以降はそれぞれのエンドポイントの実行サンプルをcurlで記載します。
また、curlの実行ディレクトリ内にjsonファイルを配置しています。
リクエストのボディはそちらに記載するようにしています。

参考: jqの利用
キャンペーン作成/有効化ともにAPI実行時にResponseが返ってきます。
パイプでjqなどに渡して整形してあげると結果を確認しやすいです。

1.キャンペーンを作成する

COMPANY_NAME、USER_NAME、SEGMENT_ID、EMAIL_IDは
利用中の環境や任意の値に適宜、読み替えてください。

terminal

curl --user "COMPANY_NAME}\USER_NAME}" -X POST -H "Content-Type: application/json" -d '@campaign.json' https://secure.p03.eloqua.com/api/REST2.0/assets/campaign

以下がPOSTする内容を記述したjsonファイルです。
ポイントは下記の2点です。

ポイント1.endAtの指定

このプロパティが設定されていない場合
「endAtがnull」が原因で、次に実行する「有効化のAPI」が動作しません。
キャンペーンの終了日時が分かってるようでしたら入力しましょう。
値そのものもUNIX TIMEを指定する必要があるため
あらかじめ変換処理が必要でした。

ポイント2.elementsの配列

キャンペーンに配置するセグメントやEメールの要素は
elementsプロパティに配列として持つようでした。
また、element同士を繋ぐ際は
繋ぎ元のelementのoutputTerminalsのプロパティで
繋ぎ先のelementのidをconnectedIdで指定する仕様なようです。
各elementのidは都合がいいように
こちらで決め打ちする形で問題ないようでした。

campaign.json

{
  "name": "CAMPAIGN_NAME",
  "elements": [
    {
      "type": "CampaignSegment",
      "id": "-1",
      "name": "Segment Members",
      "memberCount": "0",
      "memberErrorCount": "0",
      "position": {
        "x": 167,
        "y": 53
      },
      "outputTerminals": [
        {
          "type": "CampaignOutputTerminal",
          "terminalType": "out",
          "connectedId": "-2",
          "connectedType": "CampaignEmail"
        }
      ],
      "isFinished": "false",
      "isRecurring": "false",
      "segmentId": "SEGMENT_ID",
      "reEvaluationFrequency": "3600"
    },
    {
      "type": "CampaignEmail",
      "name": "Email",
      "position": {
        "x": 167,
        "y": 506
      },
      "id": "-2",
      "includeListUnsubscribeHeader": "true",
      "emailId": EMAIL_ID,
      "sendTimePeriod": "sendAllEmailAtOnce"
    }
  ],
  "endAt": "1735657200"
}

エンドポイントを実行すると
EloquaのGUIからも作成されたキャンペーンが確認できました。

2.キャンペーンを有効化する

上記のAPIの実行が完了すると
作成したキャンペーンのJSONデータがResponseとして返ってきます。
JSONからキャンペーンのIDを確認し
エンドポイントの「ID」の箇所を
実行すればキャンペーンが有効化されます。