複数のチャネルにわたって顧客の体験をリアルタイムで調整し、一貫性を保ち、パーソナライズするためには、変更が発生した場合に適切なデータを容易に利用でき、継続的に更新する必要があります。Adobe Experience Platform を使用すると、エッジと呼ばれるものを使用して、データへのこのリアルタイムアクセスを可能にします。エッジとは、データを格納し、アプリケーションから容易にアクセスできるようにする、地理的に配置されたサーバーです。たとえば、Adobe Target や Adobe Campaign などの Adobe アプリケーションは、エッジを使用して、パーソナライズされた顧客体験をリアルタイムで提供します。データは投影によってエッジにルーティングされ、データの送信先となるエッジを定義する投影先と、エッジ上で利用可能にする特定の情報を定義する投影設定があります。This guide provides detailed instructions for using the Real-time Customer Profile API to work with edge projections, including destinations and configurations.
The API endpoint used in this guide is part of the Real-time Customer Profile API. 先に進む前に、 はじめに Experience Platform 、関連ドキュメントへのリンク、このドキュメントのサンプルAPI呼び出しを読むためのガイド、APIの呼び出しを正常に行うために必要なヘッダーに関する重要な情報を確認してください。
Requests that contain a payload (POST, PUT, PATCH) require a Content-Type
header. このドキュメントでは、複数 Content-Type
が使用されています。 サンプル呼び出しのヘッダーには特に注意を払い、各リクエストで正しいヘッダーが使用されていることを確認して Content-Type
ください。
投影は、データを送信する場所を指定することで、1 つ以上のエッジにルーティングできます。作成される各投影先には一意の ID が割り当てられ、この ID を使用して投影設定が作成されます。
/config/destinations
エンドポイントに GET リクエストをおこなうことで、組織用に既に作成されているエッジの宛先をリストできます。
API 形式
GET /config/destinations
リクエスト
curl -X GET \
https://platform.adobe.io/data/core/ups/config/destinations \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
応答
応答には、各宛先の詳細が配列内の個々のオブジェクトとして表示されるprojectionDestinations
配列が含まれます。投影が設定されていない場合、projectionDestinations
配列は空を返します。
この応答はスペースを節約し、2 つの宛先のみを表示します。
{
"_links": {
"self": {
"href": "/data/core/ups/config/destinations",
"templated": false
}
},
"_embedded": {
"projectionDestinations": [
{
"_links": {
"self": {
"href": "/data/core/ups/config/destinations/cef0e2ef-5249-4e25-be90-94f5797a2841",
"templated": false
}
},
"id": "cef0e2ef-5249-4e25-be90-94f5797a2841",
"type": "EDGE",
"ttl": 3600,
"dataCenters": [
"VA5"
],
"version": 1
},
{
"_links": {
"self": {
"href": "/data/core/ups/config/destinations/7d26263f-a5df-43ce-b088-7f70e187f549",
"templated": false
}
},
"id": "7d26263f-a5df-43ce-b088-7f70e187f549",
"type": "EDGE",
"ttl": 3600,
"dataCenters": [
"OR1"
],
"version": 1
}
]
}
}
プロパティ | 説明 |
---|---|
_links.self.href |
最上位レベルでは、GET リクエストの作成に使用されるパスと一致します。個々の宛先オブジェクト内で、このパスを GET リクエストで使用して、特定の宛先の詳細を直接参照できます。 |
id |
各宛先オブジェクト内では、"id" は宛先の読み取り専用の、システム生成の一意の ID を表示します。この ID は、特定の宛先を参照する場合や、投影設定を作成する場合に使用されます。 |
個々の宛先の属性について詳しくは、次の「宛先の作成」の節を 参照してください。
必要な宛先がまだ存在しない場合は、/config/destinations
エンドポイントに POST リクエストを作成して、新しい投影先を作成できます。
API 形式
POST /config/destinations
リクエスト
次のリクエストは、新しいエッジの宛先を作成します。
宛先を作成する POST リクエストには、次に示すように、特定のContent-Type
ヘッダーが必要です。正しくないContent-Type
ヘッダーを使用すると、HTTP ステータス 415(サポートされていないメディアタイプ)エラーが発生します。
curl -X POST \
https://platform.adobe.io/data/core/ups/config/destinations \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/vnd.adobe.platform.projectionDestination+json; version=1' \
-d '{
"type": "EDGE",
"dataCenters": [
"OR1"
],
"ttl": 3600,
"replicationPolicy": REACTIVE
}'
プロパティ | 説明 |
---|---|
type (必須) |
作成する宛先のタイプ。 受け入れられる唯一の値「EDGE」は、エッジの宛先を作成します。 |
dataCenters (必須) |
投影の方向を向くエッジをリストする文字列配列。 次の値を 1 つ以上含むことができます。「OR1」- 米国西部、「VA5」- 米国東部、「NLD1」- EMEA。 |
ttl (必須) |
投影の有効期限を指定します。 許容値の範囲:600~604800。デフォルト値:3600。 |
replicationPolicy (必須) |
ハブからエッジへのデータ複製の動作を定義します。 サポートされる値:PROACTIVE、REACTIVE。デフォルト値:反応性。 |
応答
正常な応答は、読み取り専用の、システム生成の一意の ID(id
)を含む、新しく作成されたエッジ宛先の詳細を返します。
{
"self": {
"href": "/data/core/ups/config/destinations/cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4",
"templated": false
},
"id": "cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4",
"type": "EDGE",
"dataCenters": [
"OR1"
],
"ttl": 3600,
"version": 1
}
プロパティ | 説明 |
---|---|
self.href |
このパスは、宛先を直接参照(GET)するために使用され、宛先の更新(PUT)または削除(DELETE)にも使用できます。 |
id |
宛先の読み取り専用の、システム生成の一意の ID。この ID は、宛先を直接参照するため、および投影設定を作成する際に使用されます。 |
version |
この読み取り専用の値は、宛先の現在のバージョンを表示します。宛先が更新されると、バージョン番号が自動的に増分されます。 |
投影先の一意の ID がわかっている場合は、ルックアップリクエストを実行してその詳細を表示できます。これは、/config/destinations
エンドポイントに GET リクエストを行い、リクエストパスに宛先の ID を含めることでおこなわれます。
API 形式
GET /config/destinations/{DESTINATION_ID}
パラメーター | 説明 |
---|---|
{DESTINATION_ID} |
表示する投影先の一意の ID。 |
リクエスト
次のリクエストは、ルックアップ(GET)を実行して、リクエストパスで指定された ID の宛先を表示します。
curl -X GET \
https://platform.adobe.io/data/core/ups/config/destinations/9d66c06e-c745-480c-b64c-1d5234d25f4b \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
応答
応答オブジェクトは、投影先の詳細を表示します。id
属性は、リクエストで指定された投影先の ID と一致する必要があります。
{
"self": {
"href": "/data/core/ups/config/destinations/cef0e2ef-5249-4e25-be90-94f5797a2841",
"templated": false
},
"id": "cef0e2ef-5249-4e25-be90-94f5797a2841",
"type": "EDGE",
"ttl": 3600,
"dataCenters": [
"OR1"
],
"version": 1
}
既存の宛先は、/config/destinations
エンドポイントに PUT リクエストをおこない、更新対象の宛先の ID をリクエストパスに含めることで更新できます。この操作は基本的に宛先の書き換えなので、リクエストの本文には、新しい宛先を作成する際に指定するのと同じ属性を指定する必要があります。
更新リクエストに対する API 応答は直ちに行われますが、投影に対する変更は非同期で適用されます。つまり、宛先の定義を更新するタイミングと適用するタイミングに時間差があります。
API 形式
PUT /config/destinations/{DESTINATION_ID}
パラメーター | 説明 |
---|---|
{DESTINATION_ID} |
更新する投影先の一意の ID。 |
リクエスト
次のリクエストは、2 つ目の場所(dataCenters
)を含むように既存の宛先を更新します。
PUT リクエストには、次に示すように特定のContent-Type
ヘッダーが必要です。正しくないContent-Type
ヘッダーを使用すると、HTTP ステータス 415(サポートされていないメディアタイプ)エラーが発生します。
curl -X PUT \
https://platform.adobe.io/data/core/ups/config/destinations/8b90ce19-e7dd-403a-ae24-69683a6674e7 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/vnd.adobe.platform.projectionDestination+json' \
-d '{
"type": "EDGE",
"dataCenters": [
"OR1",
"VA5"
],
"replicationPolicy": REACTIVE,
"currentVersion": 1
}'
プロパティ | 説明 |
---|---|
currentVersion |
既存の宛先の現在のバージョン。宛先のルックアップリクエストを実行する際のversion 属性の値。 |
応答
応答には、宛先の ID や新しいversion
を含む、更新された宛先の詳細が含まれます。
{
"self": {
"href": "/data/core/ups/config/destinations/8b90ce19-e7dd-403a-ae24-69683a6674e7",
"templated": false
},
"id": "8b90ce19-e7dd-403a-ae24-69683a6674e7",
"type": "EDGE",
"ttl": 8000,
"dataCenters": [
"OR1",
"VA5"
],
"version": 2
}
組織で投影先が不要になった場合は、/config/destinations
エンドポイントに DELETE リクエストを送信し、削除する宛先の ID をリクエストパスに含めることで、投影先を削除できます。
削除リクエストに対する API の応答は直ちにおこなわれますが、エッジ上のデータに対する実際の変更は非同期で実施されます。つまり、プロファイルデータはすべてのエッジ(投影先で指定されたdataCenters
)から削除されますが、処理の完了には時間がかかります。
API 形式
DELETE /config/destinations/{DESTINATION_ID}
パラメーター | 説明 |
---|---|
{DESTINATION_ID} |
削除する投影先の一意の ID。 |
リクエスト
curl -X DELETE \
https://platform.adobe.io/data/core/ups/config/destinations/8b90ce19-e7dd-403a-ae24-69683a6674e7 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
応答
削除リクエストは、HTTP ステータス 204(コンテンツなし)と空の応答本文を返します。削除が成功したことを確認するには、ID で宛先のルックアップリクエストを実行します。ルックアップは、HTTP ステータス 404(見つかりません)を返す必要があります。
投影設定は、各エッジで使用可能なデータに関する情報を提供します。Rather than projecting a complete Experience Data Model (XDM) schema to the edge, a projection provides only specific data, or fields, from the schema. 組織は、各 XDM スキーマに複数の投影設定を定義できます。
/config/projections
エンドポイントに GET リクエストをおこなうことで、組織に対して作成されたすべての投影設定をリストできます。また、リクエストパスにオプションのパラメーターを追加して、特定のスキーマの投影設定にアクセスしたり、個々の投影をその名前でルックアップしたりすることもできます。
API 形式
GET /config/projections
GET /config/projections?schemaName={SCHEMA_NAME}
GET /config/projections?schemaName={SCHEMA_NAME}&name={PROJECTION_NAME}
パラメーター | 説明 |
---|---|
{SCHEMA_NAME} |
アクセスする投影設定に関連付けられているスキーマクラスの名前。 |
{PROJECTION_NAME} |
アクセスする投影設定の名前。 |
schemaName
投影設定名は、スキーマクラスのコンテキストでのみ一意であるため、name
パラメーターを使用する場合は必須です。
リクエスト
次のリクエストでは、 Experience Data Model スキーマクラスに関連付けられているすべての投影設定をリスト XDM Individual Profileします。 For more information on XDM and its role within Platform, please begin by reading the XDM System overview.
curl -X GET \
https://platform.adobe.io/data/core/ups/config/projections?schemaName=_xdm.context.profile \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
応答
成功した応答は、ルート_embedded
属性内の投影設定(projectionConfigs
配列内に含まれる)を返します。組織の投影設定がおこなわれていない場合、projectionConfigs
配列は空になります。
{
"_links": {
"self": {
"href": "/data/core/ups/config/projections",
"templated": false
}
},
"_embedded": {
"projectionConfigs": [
{
"_links": {
"destination": {
"href": "/data/core/ups/config/destinations/a689248a-5d2b-44af-bb70-c8f17f97011b",
"templated": false
},
"self": {
"href": "/data/core/ups/config/projections/99aed0bc-c183-4997-ada7-7843642e08f6",
"templated": false
}
},
"_embedded": {
"destination": {
"self": {
"href": "/data/core/ups/config/destinations/a689248a-5d2b-44af-bb70-c8f17f97011b",
"templated": false
},
"id": "a689248a-5d2b-44af-bb70-c8f17f97011b",
"type": "EDGE",
"ttl": 1000,
"dataCenters": [
"OR1"
],
"version": 1
}
},
"selector": "strategy",
"version": 2,
"id": "99aed0bc-c183-4997-ada7-7843642e08f6",
"schemaName": "_xdm.context.profile",
"name": "adcloud_rlsa",
"destinationId": "a689248a-5d2b-44af-bb70-c8f17f97011b"
},
]
}
}
エッジで使用可能にする XDM フィールドを指定する新しい投影設定を作成(POST)できます。
API 形式
POST /config/projections?schemaName={SCHEMA_NAME}
パラメーター | 説明 |
---|---|
{SCHEMA_NAME} |
アクセスする投影設定に関連付けられているスキーマクラスの名前。 |
リクエスト
The POST request to create a configuration requires a specific Content-Type
header, as shown below. 正しくないContent-Type
ヘッダーを使用すると、HTTP ステータス 415(サポートされていないメディアタイプ)エラーが発生します。
curl -X POST \
https://platform.adobe.io/data/core/ups/config/projections?schemaName=_xdm.context.profile \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/vnd.adobe.platform.projectionConfig+json; version=1' \
-d '{
"selector": "emails,person(firstName)",
"name": "my_test_projection",
"destinationId": "cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4"
}'
プロパティ | 説明 |
---|---|
selector |
エッジに複製されるスキーマ内のプロパティのリストを含む文字列。セレクターの操作に関するベストプラクティスは、このドキュメントの「セレクター」の節で参照できます。 |
name |
新しい投影設定のわかりやすい名前。 |
destinationId |
データの投影先のエッジの識別子。 |
応答
成功した応答は、新しく作成された投影設定の詳細を返します。
{
"_links": {
"destination": {
"href": "/data/core/ups/config/destinations/cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4",
"templated": false
},
"self": {
"href": "/data/core/ups/config/projections/87fcd0bc-c183-4997-daf9-7843642g95a1",
"templated": false
}
},
"_embedded": {
"destination": {
"self": {
"href": "/data/core/ups/config/destinations/cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4",
"templated": false
},
"id": "cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4",
"type": "EDGE",
"ttl": 1000,
"dataCenters": [
"OR1"
],
"version": 1
}
},
"selector": "emails,person(firstName)",
"version": 2,
"id": "87fcd0bc-c183-4997-daf9-7843642g95a1",
"schemaName": "_xdm.context.profile",
"name": "my_test_projection",
"destinationId": "cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4"
}
セレクターは、XDM フィールド名のリストをコンマで区切ったものです。投影設定では、セレクターは投影に含めるプロパティを指定します。selector
パラメーター値の形式は、XPath 構文に大まかに基づいています。次に、サポートされている構文の概要を示します。その他の参照例も示します。
foo
という名前のフィールド内にネストされているfield
フィールドを選択するには、セ レクターfoo.field
を使用します。"( )"
を使用して返されるサブフィールドをフィルタリングすることはできます。
addresses(type,city.country)
は、各addresses
配列要素の住所の種類と住所の市区町村が存在する国のみを返します。addresses.type,addresses.city.country
と同じです。サブフィールドの参照には、ドット表記と括弧の両方がサポートされています。ただし、ドット表記を使用する方がより簡潔で、フィールド階層のより良い説明を提供するため、この方法をお勧めします。
次の例は、サンプルのselector
パラメーターと、その後に表す構造化された値を示しています。
person.lastName
リクエストされたリソース内のperson
オブジェクトのlastName
サブフィールドを返します。
{
"person": {
"lastName": "Smith"
}
}
アドレス
addresses
配列内のすべての要素を返します。各要素内のすべてのフィールドが含まれますが、他のフィールドは含まれません。
{
"addresses": [
{
"type": "home",
"street1": "100 Great Mall Parkway",
"city": {
"name": "San Jose",
"country": "United States"
}
},
{
"type": "work",
"street1": "1 Main Street",
"city": {
"name": "San Jose",
"country": "United States"
}
}
]
}
person.lastName,addresses
addresses
配列内のperson.lastName
フィールドとすべての要素を返します。
{
"person": {
"lastName": "Smith"
},
"addresses": [
{
"type": "home",
"street1": "100 Great Mall Parkway",
"city": {
"name": "San Jose",
"country": "United States"
}
},
{
"type": "work",
"street1": "1 Main Street",
"city": {
"name": "San Jose",
"country": "United States"
}
}
]
}
addresses.city
住所配列内のすべての要素の市区町村フィールドのみを返します。
{
"addresses": [
{
"city": {
"name": "San Jose",
"country": "United States"
}
},
{
"city": {
"name": "San Jose",
"country": "United States"
}
}
]
}
ネストされたフィールドが返されるたびに、それを含む親オブジェクトが投影に含まれます。親フィールドも明示的に選択されていない限り、他の子フィールドは含まれません。
addresses(type,city)
addresses
配列内の各要素のtype
およびcity
フィールドの値のみを返します。各addresses
要素に含まれるその他のサブフィールドはすべて除外されます。
{
"addresses": [
{
"type": "home",
"city": {
"name": "San Jose",
"country": "United States"
}
},
{
"type": "work",
"city": {
"name": "San Jose",
"country": "United States"
}
}
]
}
This guide has shown you the steps involved in order to configure projections and destinations, including how to properly format the selector
parameter. 組織のニーズに合わせて新しい投影先や設定を作成できるようになりました。