Oracleのマーケティングオートメーション「Eloqua」のキャンペーンAPIを使ってみた件

# 前書き.この記事で分かることと考慮していないこと
## この記事で分かること
### その1.Eloqua上でAPI経由でキャンペーンを作成する方法
[Eloqua(Oracleのマーケティング業務アプリケーション)](https://www.oracle.com/jp/cx/marketing/automation/)には
[キャンペーンキャンバス機能](https://www.oracle.com/jp/cx/marketing/automation/product-tour/)があり
GUIからマーケティングキャンペーンの作成が可能です。
また、Eloquaと外部システムとの連携が必要で
**外部システムからマーケティングキャンペーンを作成したい場合**は
**APIを経由した形でもキャンペーンを作成することができる**ようでした。

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

と言いますのも、Oracle EloquaのAPIに関して
[公式のリファレンス](https://docs.oracle.com/en/cloud/saas/marketing/eloqua-rest-api/api-application-2.0-campaigns.html)がありましたが
・リクエストに含むべきミニマムの情報が分かりにくい
・必要な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.キャンペーンを有効化する

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

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

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

:::note info
参考: jqの利用
キャンペーン作成/有効化ともにAPI実行時にResponseが返ってきます。
パイプで[jq](https://qiita.com/Nakau/items/272bfd00b7a83d162e3a)などに渡して整形してあげると結果を確認しやすいです。
:::

### 1.キャンペーンを作成する
COMPANY_NAME、USER_NAME、SEGMENT_ID、EMAIL_IDは
利用中の環境や任意の値に適宜、読み替えてください。

```terminal: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は都合がいいように
こちらで決め打ちする形で問題ないようでした。

```json: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からも作成されたキャンペーンが確認できました。
![ドラフト.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3622055/15f5da10-4a58-7e94-0839-ae1c859aba00.png)


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

```terminal:terminal
curl --user "COMPANY_NAME\USER_NAME" -X POST -H "Content-Length:0"  https://secure.p03.eloqua.com/api/rest/2.0/assets/campaign/active/ここをIDに書き換えます
```

エンドポイントを実行すると
先ほどまでドラフトだったっキャンペーンがアクティブ化されています。
![アクティブ.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3622055/6dde8d1c-39d3-7943-05a0-2c59966ec42c.png)

筆者はこの段階でセグメント内のコンタクトに
メールが配信されることも確認しました。

# まとめ
昨今の業務アプリケーションはAPIを介して
外部システムと繋ぐユースケースもごく一般的になってきたと感じています。
その点、Eloquaでは今回のキャンペーンAPIだけでなく様々なAPIを提供している様子。
Eloqua外のAIや生成AIサービスと繋いで
マーケティング業務でのAI活用やユースケースの拡張も可能そうでした。

# 引用

### EloquaキャンペーンAPIのリファレンス

https://docs.oracle.com/en/cloud/saas/marketing/eloqua-rest-api/api-application-2.0-campaigns.html

### jqによるJSONの整形
https://qiita.com/Nakau/items/272bfd00b7a83d162e3a

*コードの利用は自己責任でお願いいたします。