HCL Unica Campaign REST API - V1 と V2

2020/9/3 - 読み終える時間: 9 分

REST API を使って Unica Campaign を操作する解説記事 Campaign REST API-V1 and V2 の翻訳版です。

HCL Unica Campaign REST API-V1 と V2

2020年9月2日

著者: Vishal Jadhav / Lead-Product Support Engineer

Unica Campaign は、アウトバウンド、マルチチャネル、マルチウェーブバッチキャンペーンの強力なセグメンテーション機能とトラッキング機能を備えた先進的なキャンペーン管理ソリューションです。しかし、すべてがバックグラウンドでどのように動作するのか、Campaign はスイートの他の製品とどのように接続したり、統合したりするのか。それを行うための RESTful な アプローチがあります。はい、REST API の話です。では、REST API とは何か、Campaign オブジェクトを作成する際にどのように使用されるのかは、複数の側面と領域を持つ問題です。Campaign 、オファー、オファーリスト、属性、ターゲットセルオブジェクトを操作するための HCL Campaign REST API です。

REST APIとは？

インターネットで航空券を検索して予約しようとしていて、数秒後には結果が出ている。これが API の機能であり、2つのシステムがお互いに話をするのを助けるものです。REST は、特定のルールを念頭に置いた API の作成を支援することで、このようなコミュニケーションを促進するアプローチです。

私は、Unica のサポートエンジニアとして、またクライアントアドボケイトとして働いていますが、さまざまな Unica のユースケースや質問に出くわします。私が観察してきたことの一つは、REST API コールを使用して Campaign オブジェクトを作成する際に、プラットフォームで必要な設定を行うのに苦労しているということです。課題は、サンプル JSON ボディの使用、API コールの実行に必要なパラメータ、または REST API の任意のバージョンの構成値の更新のように、さまざまな場合があります。この記事では、プラットフォームでの設定を理解し、実行するために役立つことに焦点を当てています。REST API の呼び出しを実行するためには、REST API の呼び出しを操作しながら、多くのユーザーやクライアントに利用されている Postman ツールを使用します。

プラットフォーム側の設定

1. APIコールで認証に使用されるトークンの有効期間を延長します。

• 次へナビゲートします: Affinium|Manager|miscellaneous

• 必要に応じてトークンのライフタイムの値を増やします。秒単位です。

2. 2. API 認証の設定を変更します。

• Affinium|suite|security|apiSecurity|manager|managerAuthentication に移動します。

• すべてのプロパティを無効にします。

• 「API アクセスに認証を必要とする」を true にしておくと、API コールに使用されたユーザーのパスワードが検証されます。

• 設定＞ユーザーからユーザーにパスワードを設定してください。無効にしている場合は、パスワードを渡す必要はありません。

3. Affinium|suite|security|apiSecurity|manager|Logout に移動し、以下のように設定値を変更します。

4. Rest API Ver1.0の更新設定

• Affinium|suite|security|apiSecurity|Campaign|Campaign REST API V2 Filterに移動します。

• 設定値を更新します。下のスクリーンショットを参照してください。

• アプリケーションサーバーを再起動します。

APIコールを実行する Postman ツール

Postman はソフトウェア開発ツールです。これは、人々がAPIへの呼び出しをテストすることを可能にします。Postman のユーザーはデータを入力します。データは特別な Web サーバーのアドレスに送信されます。通常、情報が返され、Postman はユーザーに提示します。任意のツールを使用することができますが。主な目的は、API コールをしようとしている間に必要な詳細を提供することです。呼び出しタイプ、リクエストパラメータ (ヘッダ、ボディ) 、実行に必要な URL などのパラメータがあります。

1. POST API コールを実行してトークンを取得し、認証のための API コールで使用できるようにします。

<span style="font-weight: 400;">Call: POST</span>
URL : http://<HostName:Port>/unica/api/manager/authentication/login/
Headers :
M_user_name > user used for API calls for e.g. asm_admin
M_user_password > password set for user.

2. このトークンIDは、Campaign rest API の API コールを任意に投稿する際に使用できます。オファーをリストダウンします。

Call: GET
URL : http://<HostName:Port>/ Campaign/api/campaign/rest/v2/offers/search?search
Headers :
m_user_name  > asm_admin
m_tokenid         > <TokenID captured in platform post call>
api_auth_mode > manager

「検索」文字列では、任意の文字列値を渡すことで、特定のオファーを検索できます。

REST V2の例

特定のオファーの詳細をリストアップします。

Call: GET
URL : http://<hostname:port>/Campaign/api/campaign/rest/v2/offers/29
Where 29 is offerID . Pass any offer ID for which you need to fetch the details.
Headers :
m_user_name > asm_admin
m_tokenid > <TokenID captured in platform post call>
api_auth_mode > manager

レスポンス .

Campaign でオファーを作成するには？

Call: POST URL : http:///Campaign/api/campaign/rest/v2/offers

• Header

  m_user_name > asm_admin
  m_tokenid > <TokenID captured in platform post call>
  api_auth_mode > manager
  Content-Type > application/json

• クエリパラメータでは、以下の値を渡します。 securityPolicy: 例えば 'Global Policy' などのポリシー名。 folderid: オファーを作成する必要があるフォルダID。 templateName: Campaign オファー作成のためのオファーテンプレート名。

• Body. 行のラジオボタンを選択し、JSON ボディを送信します。 それは、オファー名とパラメータを持っています。パラメータが渡されていない場合は、デフォルトのパラメータ値でオファーを作成します。

[ {
"offerName":"RESTNewOffer_IP1",
"attributes":[]
} ]

REST V1 の例

Campaign オファー作成のための v1 rest APIを 実行するには？

• 設定手順はすべて先ほど定義したものと同じです。
• 同じ手順でプラットフォームの tokenID をフェッチします。

• 唯一の違いは、APIコールで渡す必要があるデータの入力タイプです。 v2では、入力データを生のJSONとして渡していることがわかりました。 v1では、すべてのパラメータを x-www-form-urlencoded として渡す必要があります。

  Call: POST URL : http:///Campaign/api/campaign/rest/v1/offers

Headers :

m_user_name > asm_admin
m_tokenid > <TokenID captured in platform post call>
api_auth_mode > manager

コンテンツタイプを追加する必要はありませんが、選択する入力タイプで自動的にピックアップされます。 Body セクションの x-www-form-urlencoded のラジオボタンを選択し、以下の値を入力してください。

securityPolicy: Policy name for e.g. ‘Global Policy’
folderid: folder ID under which we need to create offers for e.g. 4 [root folder for offers]
templateName: campaign offerTemplate name from which offers to be created .
BulkOfferInfo : [{"offerName":"Offer API","attributes":[]}]

オファー名とパラメータを渡します。パラメータを渡さない場合は、デフォルトのパラメータ値でオファーが作成されます。リクエストとレスポンスは以下のスクリーンショットを参照してください。

オファーのパラメータを渡したい場合は、必要に応じてパラメータ値を追加して、リクエスト本文を更新します .

BulkOfferInfo:
[
{"offerName":"Offer Interact API_3",
"attributes":[
{"type":"TextAttribute","name":"ABC_TXT","value":"XYZ"},
{"type":"DecimalAttribute","name":"UACIInteractionPointID","value":2.0},
{"type":"TextAttribute","name":"UACIInteractionPointName","value":"IP2"}
]
}]

Campaign REST API の呼び出しにより、Campaign オブジェクト (オファー、キャンペーンの作成) の create+update+delete+List のような操作を Unica アプリケーションにログインすることなく実行することができます。Campaign とREST API の連携については、お気軽にお問い合わせください。