IBM Campaign REST API
IBM® Campaign REST API を使用して、キャンペーン、オファー、オファー・リスト、属性、およびターゲット・セル・オブジェクトを操作できます。
概要
この API は REST (Representational State Transfer) の原則に基づいているので、アプリケーションを簡単に作成してテストできます。ご使用のブラウザーで URL にアクセスしたり、任意のプログラミング言語の標準的な HTTP クライアントを使用してこの API と対話したりできます。すべての API 呼び出しは、全部小文字でなければなりません。
ベース URL
ベース URL は次のとおりです。 http://<host>:<port>/Campaign/api/campaign/rest
下記にリストするすべての API の前に、このベース URL を付加してください。以下に例を示します。 http://host:port/Campaign/api/campaign/rest/v1/offers
API のリスト
| 属性 | |
| get: /v1/attributes | 定義されているすべての属性または指定された属性のメタデータを戻します。 |
| POST /v1/attributes/create/{type} | 指定されたオブジェクト・タイプの属性メタデータを作成します。 |
| delete: /v1/attributes/delete | 指定された属性のメタデータを削除します。 |
| get: /v1/attributes/metadata/{type} | 指定されたタイプのすべての属性または指定された属性のメタデータを戻します。 |
| put: /v1/attributes/update/metadata | 指定されたオブジェクトの属性値を更新します。 |
| put: /v1/attributes/update/{type}/{id} | 指定されたオブジェクトの属性値を更新します。指定された属性のメタデータを戻します。 |
| get: /v1/attributes/{type}/{id} | 指定された属性のメタデータを戻します。 |
| キャンペーン | |
| get: /v1/campaigns | JSON データ形式でキャンペーン・オブジェクトのリストを戻します。 |
| POST /v1/campaigns | 提供された JSON データでキャンペーンを作成します。 |
| get: /v1/campaigns/code | キャンペーン・コードを生成します。 |
| POST /v1/campaigns/delete | 指定されたキャンペーンを削除します。 |
| get: /v1/campaigns/metrics | 指定されたキャンペーンのメトリックを戻します。 |
| POST /v1/campaigns/search | 提供された情報に基づいてキャンペーンを検索します。 |
| get: /v1/campaigns/{campaignid} | 指定されたキャンペーン・オブジェクトを戻します。 |
| put: /v1/campaigns/{campaignid} | 指定されたキャンペーン・オブジェクトを更新します。 |
| delete: /v1/campaigns/{campaignid} | 指定されたキャンペーン・オブジェクトを削除します。 |
| オファー | |
| POST /v1/offers | 1 つ以上のオファーを作成します。 |
| post: /v1/offers/delete | 1 つ以上のオファーを削除します。 |
| get: /v1/offers/gencode | 1 つ以上の固有のオファー・コードを生成します。 |
| post: /v1/offers/getoffers | すべてのオファー・オブジェクトをリストします。 |
| POST /v1/offers/retire | 1 つ以上のオファーを回収します。 |
| POST /v1/offers/templates | オファー・テンプレートの詳細と一緒にリストを戻します。 |
| POST /v1/offers/validate | 一致するオファーが 1 つのみ存在するかどうかを検査します。 |
| オファー v2 | |
| POST /v2/offers | 1 つ以上のオファーを作成します。 |
| POST /v2/offers/delete | 1 つ以上のオファーを削除します。 |
| get: /v2/offers/gencode | 1 つ以上の固有のオファー・コードを生成します。 |
| POST /v2/offers/getoffers | すべてのオファー・オブジェクトをリストします。 |
| POST /v2/offers/retire | 1 つ以上のオファーを回収します。 |
| POST /v2/offers/templates | オファー・テンプレートの詳細と一緒にリストを戻します。 |
| POST /v2/offers/validate | 一致するオファーが 1 つのみ存在するかどうかを検査します。 |
| get: /v2/offers/search | 詳細なオファーのリストを返します。 |
| get: /v2/offers | |
| オファー・リスト | |
| get: /v1/offerlist | オファー・リストのリストを戻します。 |
| put: /v1/offerlist | オファー・リストを更新します。 |
| POST /v1/offerlist | オファー・リストを作成します。 |
| POST /v1/offerlist/createSmartOffer | スマート・オファー・リストを作成します。 |
| POST /v1/offerlist/delete | オファー・リストを削除します。 |
| POST /v1/offerlist/retire | オファー・リストを回収します。 |
| ターゲット・セル・オブジェクト | |
| get: /v1/targetcells | 指定されたキャンペーン ID のターゲット・セルのリストを戻します。 |
| POST /v1/targetcells | 提供された情報でターゲット・セルを作成します。 |
| POST /v1/targetcells/delete | 指定されたターゲット・セルを一括削除します。 |
| get: /v1/targetcells/runresults | 指定されたターゲット・セルの実行結果を戻します。 |
| put: /v1/targetcells/update | 提供された情報で既存のターゲット・セルを更新します。 |
| delete: /v1/targetcells/{cellid} | 指定されたターゲット・セルを削除します。 |
HTTP 状況コード
200 - OK 400 - 誤った要求 (エラーを修正してから再送信してください)。500 - 内部サーバー・エラー (Campaign Web アプリケーション・サーバーの <Campaign_home>/logs/campaignweb.log で詳細を確認してください)。404 - 見つかりません。
多数のオンライン・リソースで、HTTP 状況コードに関する情報が提供されています。IBM Marketing Software API のセキュリティー・フレームワーク
Marketing Platform は、IBM Marketing Software 製品によって実装される API のセキュリティー・フレームワークを提供します。
ページの構成プロパティーのセットにより、開発者は IBM Marketing Software 製品によって提供されている API の以下のセキュリティーを設定することができます。
- 特定の製品 API では、製品へのアクセスをブロックすることができます。
- 特定の製品 API では、指定された API と製品の間の通信に HTTPS を要求することができます。
- 特定の製品 API では、指定された API と製品の間の通信に認証を要求することができます。
API セキュリティーを制御する構成プロパティーは、IBM Marketing Platform | セキュリティー | API 管理カテゴリーの下にあります。各製品には、製品ごとに提供されている API の新規セキュリティー設定を作成するために使用できる構成プロパティーのテンプレートがあります。
API のセキュリティー設定は、単体テストまたはデプロイメントごと、または API のライフサイクル全体で、必要に応じて設定および変更することができます。
セキュリティー・フレームワークは現在、Campaign の API のみをサポートしています。
Marketing Platform セキュリティー・フレームワークでは、保護された API にアクセスするために次の 2 つの認証オプションをサポートしています。使用環境に応じていずれかを使用できます。
- Marketing Platform に登録されている内部ユーザーは、セキュア・トークンを取得するために各自の Marketing Platform ログイン資格情報を使用して認証できます。
- Marketing Platform で使用するようにセットアップしたフェデレーションに含まれる外部ユーザーは、ID プロバイダー・サーバーを介して認証できます。
Marketing Platform ログイン API を使用した内部ユーザー認証
クライアント・アプリケーションで内部ユーザーを認証するには、Marketing Platform login API を使用して、セキュア・トークンを生成します。その後、API 自体で必要なパラメーターに加えて、要求ヘッダーに必要なパラメーターを渡すことにより、保護された API を呼び出すことができます。
セキュリティー・フィルターは、処理を行うために、保護された要求を代行受信、妥当性検査、およびパススルーします。
Marketing Platform ユーザーが認証された後、Marketing Platform セキュリティー・フィルターは、処理のために製品に渡す前に、USER_NAME_STRING キーの属性としてユーザーのログイン名を要求に追加します。
セキュア・トークンには、15 秒というデフォルトのライフ・スパンがあります。トークンのライフ・スパンが満了した後、保護された API を呼び出すためにそのトークンを使用することはできなくなります。ユーザーに対して Marketing Platform login API が呼び出されるたびに、そのユーザーの以前のセキュリティー・トークンはすべて無効になります。
全般 | その他カテゴリーの下のページにある「トークンの存続時間」プロパティーの値を設定することにより、セキュア・トークンのライフ・スパンを変更することができます。
URL の例
http[s]://host:port/unica/api/manager/authentication/login/
ヘッダー・パラメーター
| パラメーター | 説明 |
|---|---|
| m_user_name | 内部ユーザーの Marketing Platform ログイン名。 |
| m_user_password | プレーン・テキストでの内部ユーザーの Marketing Platform パスワード。 |
レスポンス
ログインに成功すると、応答 HTTP 200 が以下の JSON データとともに返されます。
- m_tokenId - ランダムに生成されるトークン
- m_user_name - ログイン・ユーザーのユーザー名
- createDate - 以下の例で示されている形式のタイム・スタンプ (タイム・ゾーンは IST)。
Mon Jul 06 18:23:35 IST 2015
正しくない資格情報によってログインに失敗すると、応答 HTTP 401 (無許可) が返されます。ブロックされるよう login API が構成されている場合、応答 403 (禁止) が返されます。HTTPS を使用するよう login API が構成されている場合に HTTP で呼び出されると、応答 403 (禁止) が返されます。
内部ユーザーをログアウトするには、Marketing Platform logout API を使用します。
Marketing Platform ログアウト API による内部ユーザーのログアウト
Marketing Platform logout API を使用して、内部ユーザーをログアウトし、セキュア・トークンを削除します。
logout API はデフォルトで保護されています。事前定義キーに対する要求ヘッダーには、認証パラメーターが必要です。
URL の例
http[s]://host:port/unica/api/manager/authentication/logout/
ヘッダー・パラメーター
| パラメーター | 説明 |
|---|---|
| m_user_name | 内部ユーザーの Marketing Platform ログイン名。 |
| m_tokenId | 認証によって入手されるセキュア・トークン。 |
| api_auth_mode | 内部ユーザーに対して値 manager を使用します。 |
レスポンス
認証に成功すると、応答 HTTP 200 が返され、セキュア・トークンが削除されます。応答が HTTP 200 である場合、クライアント・アプリケーションによってログアウトが確認されます。
認証に失敗すると、応答 HTTP 401 が返されます。
フェデレーションによる外部ユーザー認証とログアウト
サポートされているフェデレーションと Marketing Platform が統合されると、ユーザーは自分のシステムにログインすることが可能になり、クライアント・アプリケーションは Marketing Platform によって提供される ID プロバイダー (IdP) サーバーを介してトークンを取得します。
フェデレーテッド・ユーザーを認証した後、対応する Marketing Platform ログイン名が USER_NAME_STRING キーの属性として要求に追加されます。
IdP サーバーでログアウトを行う必要があります。
ヘッダー・パラメーター
以下の表では、Marketing Platform によって提供される IdP サーバーを介して認証するときに使用するヘッダー・パラメーターについて説明しています。
| パラメーター | 説明 |
|---|---|
| f_userId | フェデレーションでのユーザー ID。 |
| f_clientId | フェデレーションでのクライアント ID。 |
| f_spId | フェデレーションでのサービス・プロバイダー ID。 |
| f_tokenId | IdP サーバーからのシングル・サインオン・トークン。 |
| api_auth_mode | フェデレーテッド認証に対して値 fsso を使用します。 |
レスポンス
応答は HTTP 200 です。これに加えて、API に応じた追加の項目が返されます。