CRMデータをオンボーディングするためのOracle OnRamp APIの使用方法
CRMデータのオンデマンド・オンボーディングとアクティブ化に、OracleのOnRamp APIを使用できます。OnRamp APIが提供する自動化されたプログラマティックなソリューションによって、マッチ率を最大化し、より多くのデータをより頻繁に、かつ必要なときにいつでもオンボーディングできます。OnRamp APIを使用すると、CRMデータベースのユーザーをセグメント化して、顧客の個人識別情報(PII)を伴うAPIコールを安全に実行できます。
OnRampによってオフライン・ユーザーが照合され、その属性が、Oracle Data Cloudプラットフォームのプライベート・タクソノミの新しいカテゴリに分類されます。これにより、ターゲッティング、分析、モデリングおよび最適化のために、複数のメディア実行プラットフォームをまたいでCRMデータをアクティブ化できます。
OnRamp APIには、次のメリットがあります。
- セルフサービス・オンボーディング: オンデマンドで自分のPIIをアップロードして新しい値を含めることで、新しいデータを収集し、タクソノミをカスタマイズします。
- プログラマティックで自動化されたオンボーディング: オフラインのオンボーディング・プロセスを削減する、迅速で自動化されたワークフローを使用します。OnRamp APIを使用すると、CRMデータをプログラマティックにインポートして、Oracle Data Cloudプラットフォームで自動的に分類できます。
- マッチ率の最大化: Oracle ID GraphのプラットフォームとDLXのCookieの重複を活用して、カスタマ・ベースをさらにアクティブ化します。
ノート: ユーザーがOracle Data CloudプラットフォームUIでキャンペーンを作成することはなくなりました。キャンペーン・ワークフローは、オーディエンス・ワークフローの一部になりました。ただし、プラットフォームでは引き続きキャンペーンを使用して、オーディエンス・データ配信を管理できます。キャンペーンは、UIユーザーがオーディエンスを配信する際に自動的に作成されます。APIでは、以前と同様にキャンペーンを作成して使用します。
このトピックの内容
要件
OnRamp APIを使用するには、次の要件を満たしている必要があります。
- OnRamp APIキー。OnRamp APIに対する各コールで、キーを渡す必要があります。OnRamp APIキーを取得するには、Oracle Data Cloudの担当者に連絡します。クライアントIDとクライアント秘密キーが、2つの異なる電子メールで配信されます。
- PII。マッチ率を最大化するには、可能なかぎり多くのカスタマ・データを提供する必要があります。ただし、ユーザーを照合するには、次のPIIの組合せを1つ以上指定する必要があります。
- 名、姓、番地、市町村、州、郵便番号。
- 名、姓、郵便番号。
- 電子メール・アドレス。
- ハッシュ化された電子メール・アドレス(SHA-256、SHA-1またはMD5)。
- 国。米国に居住しているユーザーのCRMデータのみをオンボーディングできます。現在、他の国のオンボーディングはサポートされていません。
- OnRampアプリ。Oracle Data CloudプラットフォームでOnRampアプリにアクセスする必要があります。
スタート・ガイド
OnRamp APIを使用してCRMデータをオンボーディングするには、オーディエンスの作成、セグメントの作成、セグメントへのユーザーの追加のための3つのPOSTリクエストが必要です。
| ステップ | 説明 | エンドポイント | |
|---|---|---|---|
| 1 | オーディエンスの作成 |
オーディエンスは、アップロードされるCRMファイルを表します。オーディエンスには、1つ以上のセグメント(属性または行動が同じユーザーの分類)が含まれます。このPOSTレスポンスには、続くセグメントとユーザーのAPIコールに必要なオーディエンスIDが含まれます。 |
https://portal.datalogix.com/audience-onramp/api/v1/audiences |
| 2 | セグメントの作成 | セグメントは、特定のユーザー分類(年齢、性別、コーヒーと紅茶のどちらを好むかなど)を含む、CRMファイルの列を表します。セグメントは、DMPタクソノミの新しいカテゴリにマッピングされます。 | https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/segments |
| 3 | セグメントへのユーザーの追加 | セグメントに追加されるユーザーのPII。ユーザーは、セグメントに追加すると、DMPタクソノミのカテゴリに分類されます。 | https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/users |
オーディエンスの作成
オーディエンスは、アップロードされるCRMファイルを表します。オーディエンスには、1つ以上のセグメント(属性または行動が同じユーザーの分類)が含まれます。
オーディエンスを作成するには、https://portal.datalogix.com/audience-onramp/api/v1/audiencesに対して、オーディエンスのnameとdescriptionを指定し、segmentationEnabledをtrueに設定したJSON本文を指定したPOSTリクエストを実行します。次の例は、JSON本文を示しています。
{
"name": "Coffee Drinkers",
"description": "An offline file with the age, gender, and drink preference (coffee or tea) of customers",
"segmentationEnabled": true
}
POSTレスポンスには、オーディエンスに対して生成されたユニークID (12345など)と、HTTP 201成功コード(オーディエンスの作成の成功)が含まれます。
{
"audienceId": 12345
}
セグメントの作成
セグメントは、特定のユーザー分類(年齢、性別、コーヒーと紅茶のどちらを好むかなど)を含む、CRMファイルの列を表します。セグメントは、DMPタクソノミの新しいカテゴリにマッピングされます。
セグメントを作成するには、https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/segmentsに対して、次のものを指定したPOSTリクエストを実行します。
- オーディエンスを作成したときに返されたオーディエンスID (https://portal.datalogix.com/audience-onramp/api/v1/audiences/12345/segmentsなど)
- セグメントのリストを含むJSON本文。
各セグメントには、キーと値のペアを表すclassificationNameとsegmentNameが含まれます。たとえば、genderセグメントを指定するには、2つのセグメントを作成します(一方はclassificationNameがgenderに設定されてsegmentNameがfemaleに設定されたセグメントで、もう一方はclassificationNameがgenderに設定されてsegmentNameがmaleに設定されたセグメント)。
次の例は、age、genderおよびdrinkのセグメントのあるJSON本文を示しています。
{"segments":[
{
"classificationName":"gender",
"segmentName":"female"
},
{
"classificationName":"gender",
"segmentName":"male"
},
{
"classificationName":"age",
"segmentName":"18-35"
},
{
"classificationName":"age",
"segmentName":"35-65"
},
{
"classificationName":"drink",
"segmentName":"coffee"
},
{
"classificationName":"drink",
"segmentName":"tea"
}
]
}
POSTレスポンスには、作成された分類のIDおよびセグメントのIDと、HTTP 201成功コード(セグメントの作成の成功)が含まれます。
{
"segments":[
{
"classificationId":208900,
"segmentId":208901,
"classificationName":"gender",
"segmentName":"female"
},
{
"classificationId":208902,
"segmentId":208903,
"classificationName":"gender",
"segmentName":"male"
},
{
"classificationId":208904,
"segmentId":208905,
"classificationName":"age",
"segmentName":"18-35"
},
{
"classificationId":208906,
"segmentId":208907,
"classificationName":"age",
"segmentName":"35-65"
},
{ "classificationId":208908,
"segmentId":208909,
"classificationName":"drink",
"segmentName":"coffee"
},
{
"classificationId":208910,
"segmentId":208911,
"classificationName":"drink",
"segmentName":"tea"
}
]
}
セグメントへのユーザーの追加
ステップ2で作成したセグメントにユーザーを追加するには、https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/usersに対して、(1) URIにステップ1で取得したオーディエンスID (https://portal.datalogix.com/audience-onramp/api/v1/audiences/12345/usersなど)と、(2)項目のリストを含むJSON本文を指定したPOSTリクエストを実行します。各項目には、ユーザーのPII、追加先のセグメントおよびAPPENDに設定されたoperationが含まれます。最小限、PIIは、次の組合せのいずれかとなります。
- 名、姓、番地、市町村、州、郵便番号。
- 名、姓、郵便番号。
- 電子メール・アドレス。
- ハッシュ化された電子メール・アドレス(SHA-256、SHA-1またはMD5)。
マッチ率の最大化。マッチ率を最大化して、可能なかぎり多くのデータをオンボーディングするには、ユーザーについて把握しているすべてのPIIを指定します。
次の例は、ユーザーの住所、電子メール・アドレスおよびSHA-256電子メール・ハッシュに基づいて、ステップ2で作成したfemale、35-65およびcoffeeのセグメントにユーザーを追加するJSON本文を示しています。
{
"items":[
{
"operation":"APPEND",
"segments":{"gender":"female", "age":"35-65", "drink":"coffee"},
"firstName":"Joe",
"lastName":"Smith",
"address1":"120 Elm St.",
"address2":"#600",
"city":"San Diego",
"state":"CA",
"zip":"92102",
"email":"joe.smith@yahoo.com",
"emailSha256":"5072c9c307c2b5a7ea4aaac9722fa45cbe3537e98240afaecba88e3071c379bc"
}
]
}
POSTレスポンスには、HTTP 202成功コード(ユーザーの追加の成功)が含まれます。
{
"body":{},
"statusCode":"202",
"statusCodeValue":0
}
OnRampによるカテゴリの作成
セグメントにユーザーを追加すると、OnRampによって、各セグメントに対応したカテゴリがOracle Data Cloudプラットフォームのタクソノミに作成されます。また、セグメントを新しいカテゴリにオンボーディングする分類ルールも作成されます。データがオンボーディングされた後、{プラットフォームのカテゴリID}-{DLXオーディエンス名}の構文を持つカテゴリ名(36524-Smartphone Buyersなど)で、セグメントに対して作成されたカテゴリがDMPタクソノミの「Self-Classification」ノードに表示されます。ターゲット・オーディエンスに新しいカテゴリを追加して、複数のメディア実行プラットフォームをまたいでオーディエンスを配信するキャンペーンを作成できます。オーディエンスとキャンペーンは、Oracle Data CloudプラットフォームのUIまたはOracle Data CloudプラットフォームのオーディエンスAPIおよびキャンペーンAPIを使用して作成できます。
OnRamp APIリクエストの認証
APIのセキュリティ・モデルは、AWS、Oracleのクラウド・インフラストラクチャおよびその他のパブリックAPIプラットフォームで使用されるHMAC (Hash-based Message Authentication Code)に基づきます。基本のアルゴリズムで、Oracle Data Cloud APIセキュリティ・ゲートウェイとアプリケーションの両方に認識されるHMACキーを使用して、HTTPリクエストの選択部分(署名文字列)がハッシュ化されます。次に、結果のハッシュ化された文字列(署名)がリクエストに含まれます。各APIリクエストには、アクティビティを識別する特定のHTTPヘッダーが含まれる必要があります。これらのヘッダーが欠落しているか、不完全であるか、誤っている場合、HTTP/401 (禁止)エラーが表示されてリクエストが失敗します。
GET
リクエストには、Hostヘッダー、DateヘッダーおよびAuthorizationヘッダーが含まれる必要があります。HostヘッダーとDateヘッダーが標準の場合、Authorizationヘッダーを次のように書式設定する必要があります。
3AMP version="1",keyId="<clientId>",headers="(resource-target) host date",algorithm="hmac-sha256", signature="<signature>"
<clientId>の値は提供されますが、<signature>の値は、次のように(ノート: 小文字)クライアント・シークレットを使用することにより、Base64でエンコードされたSHA256ハッシュ値を使用してリクエストごとに計算する必要があります。
get<request path><host header value><date header value>
POST
次のヘッダーが含まれる必要があります。
- Host
- Date
- Content-Type
- Content-Length
- X-Content-SHA256: これは、POST本文のハッシュです。
Authorizationヘッダーは次のようになります。
3AMP version="1",keyId="<clientId>",headers="(resource-target) host date content-type content-length x-content-sha256",algorithm="hmac-sha256", signature="<signature>"
PUT
これはPOSTリクエストと同じです。
DELETE
これはGETリクエストと同じです。
Javaの例
この項では、JavaでHMAC MD5署名を作成する方法の例を示します。
import org.glassfish.jersey.client.JerseyClientBuilder;
import org.glassfish.jersey.client.ClientConfig;
import javax.ws.rs.client.Client;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Base64;
import java.util.Date;
import java.util.Locale;
import java.util.TimeZone;
public class OnRampApiExample {
private static final String Host = "https://portal.datalogix.com";
private static final String Algorithm = "HmacSHA256";
private static final String GetHeaderFmt = "3AMP version=\"1\",keyId=\"%1$s\",headers=\"(resource-target) host date\",algorithm=\"hmac-sha256\",signature=\"%2$s\"";
private static final String PostHeaderFmt = "3AMP version=\"1\",keyId=\"%1$s\",headers=\"(resource-target) host date x-content-sha256 content-length content-type\",algorithm=\"hmac-sha256\",signature=\"%2$s\"";
private static final String Rfc2822FmtStr = "EEE, dd MMM yyyy HH:mm:ss zzz";
private static final DateFormat Rfc2822Fmt = new SimpleDateFormat(Rfc2822FmtStr, Locale.US);
private static final Mac Hmac;
// Replace these values
private static final String ClientId = "***REDACTED***";
private static final String Secret = "***REDACTED***";
static {
try {
System.setProperty("sun.net.http.allowRestrictedHeaders", "true");
Hmac = Mac.getInstance(Algorithm);
} catch (Exception ex) {
throw new RuntimeException(ex);
}
}
private static void post(String payload, String host, String uri, String clientID, String clientSecret) throws Exception {
Hmac.init( new SecretKeySpec(clientSecret.getBytes("UTF-8"), Algorithm) );
Rfc2822Fmt.setTimeZone(TimeZone.getTimeZone("GMT"));
// Set up the request
URL url = new URL(host + uri);
ClientConfig config = new ClientConfig();
Client client = JerseyClientBuilder.newClient(config);
// Build the signing string and the Authorization header
String rfc2822 = Rfc2822Fmt.format( new Date() );
String sha256 = getSha256(payload);
int clen = payload.getBytes("UTF-8").length;
String ctype = MediaType.APPLICATION_JSON;
String signingStr = ("post"+url.getPath()+url.getHost()+rfc2822+sha256+clen+ctype).toLowerCase();
String signature = new String(Base64.getEncoder().encode(Hmac.doFinal(signingStr.getBytes("UTF-8"))), "UTF-8");
String authHeader = String.format(PostHeaderFmt, clientID, signature, sha256, clen, ctype);
// Add the headers declared by the authorization to the request
// Initiate the request
Response response = client
.target(host)
.path(uri)
.request(MediaType.APPLICATION_JSON_TYPE)
.header("Date", rfc2822)
.header("Authorization", authHeader)
.header("X-Content-Sha256", sha256)
.header("Content-Length", clen)
.header("Content-Type", ctype)
.post(Entity.entity(payload, MediaType.APPLICATION_JSON_TYPE));
if (response.getStatus() != 201 && response.getStatus() != 202 && response.getStatus() !=200 ) throw new IOException("Bad response: "+response.getStatus());
System.out.println(response.getStatus());
System.out.println(response.readEntity(String.class));
}
private static void getRequest(String host, String uri, String clientID, String clientSecret) throws Exception {
Hmac.init(new SecretKeySpec(clientSecret.getBytes("UTF-8"), Algorithm));
Rfc2822Fmt.setTimeZone(TimeZone.getTimeZone("GMT"));
// Set up the request
URL url = new URL(host + uri);
ClientConfig config = new ClientConfig();
Client client = JerseyClientBuilder.newClient(config);
// Build the signing string and the Authorization header
String rfc2822 = Rfc2822Fmt.format(new Date());
String signingStr = ("get" + url.getPath() + url.getHost() + rfc2822).toLowerCase();
// String signature = Base64.encodeBase64String(Hmac.doFinal(signingStr.getBytes("UTF-8")));
String signature = new String(Base64.getEncoder().encode(Hmac.doFinal(signingStr.getBytes("UTF-8"))), "UTF-8");
String authHeader = String.format(GetHeaderFmt, clientID, signature);
// Initiate the request
Response response = client
.target(host)
.path(uri)
.request(MediaType.APPLICATION_JSON_TYPE)
.header("Date", rfc2822)
.header("Authorization", authHeader)
.get();
if (response.getStatus() != 200) throw new IOException("Bad response: " + response.getStatus());
System.out.println(response.readEntity(String.class));
}
private static String getSha256(String text) throws NoSuchAlgorithmException,UnsupportedEncodingException {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(text.getBytes(StandardCharsets.UTF_8));
return new String(Base64.getEncoder().encode(hash), "UTF-8");
}
public static void main(String[] args) throws Exception {
boolean getExample = false;
if (getExample) {
String uri = "/audience-onramp/api/v1/audiences/3392037";
getRequest(Host, uri, ClientId, Secret);
} else {
String payload = "{\"name\":\"test_audience_123\"}";
String uri = "/audience-onramp/api/v1/audiences";
post(payload, Host, uri, ClientId, Secret);
}
}
}
OnRamp APIプログラマーズ・リファレンス
次の項では、OnRamp APIのメソッドとレスポンス・コードの詳細を示します。
メソッド
次の表では、OnRampのオーディエンス、セグメントおよびユーザーのAPIでサポートされるメソッドとパラメータの詳細を示します。
| API | HTTPメソッド | エンドポイント | 説明 | GETレスポンス/ POSTリクエスト本文 |
|||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| オーディエンス |
POST |
https://portal.datalogix.com/audience-onramp/api/v1/audiences |
オーディエンスを作成します。 |
OnRampオーディエンスAPI - POSTリクエスト: JSON本文のパラメータ
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
| GET (リスト) |
https://portal.datalogix.com/audience-onramp/api/v1/audiences? |
オーディエンスの詳細と指標のリストを取得します。 |
OnRampオーディエンスAPI - GETリクエスト(リスト): URIパラメータ
OnRampオーディエンスAPI - GETリクエスト(読取り): URIパラメータ
OnRampオーディエンスAPI - GETレスポンス: JSON本文のパラメータ
|
||||||||||||||||||||||||||||||||||||||||||||||||||||
| GET (読取り) | https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId} | 特定のOnRampオーディエンスの詳細と指標を取得します。 | |||||||||||||||||||||||||||||||||||||||||||||||||||||
| セグメント | POST |
https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/segments |
オーディエンスにセグメントを追加します。 |
OnRampセグメントAPI - POSTリクエスト: JSON本文のパラメータ
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
| ユーザー | POST | https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/users | セグメントにユーザーを追加します。 |
OnRampユーザーAPI - POSTリクエスト: JSON本文のパラメータ
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
HTTPレスポンス・コード
OnRamp APIリクエストでは、HTTPステータス・コードとメッセージの説明を含む次のJSON形式のデータが返されます。
| HTTPステータス・コード | メッセージの説明 | API |
|---|---|---|
| 201 | オーディエンスが正常に作成されました。 | オーディエンスPOST セグメントPOST |
|
202 |
ユーザーが正常に追加されました。 |
ユーザー |
|
400 |
無効なリクエストです。これは、POSTリクエストの本文のパラメータが欠落しているか、JSONの形式が正しくないことを示している可能性が最も高いです。 |
すべて |
| 401 | 認可されていません。これは、OnRamp APIコールに、有効なAPIキーまたは有効なメソッドの署名がないことを示しています。 |
すべて |
| 404 | 見つかりませんでした。指定されたオーディエンスIDのオーディエンスが存在しません。 | オーディエンスGET (読取り) |
|
500 |
内部エラー。これは、OnRamp APIのサービス・エラーを示しています。Oracle Data Cloudの担当者に連絡してください。 |
すべて |