边缘投影配置和目标端点

为了跨多个渠道为客户实时提供协调、一致和个性化的体验,需要随时提供适当的数据,并在发生更改时不断更新。 Adobe Experience Platform允许通过使用称为边缘的内容来实时访问数据。 边缘是位于地理位置的服务器,用于存储数据并使应用程序能够轻松访问它。 例如,Adobe应用程序(如Adobe Target和Adobe Campaign)使用边缘,以便实时提供个性化的客户体验。 数据通过投影被路由到边缘,其中,投影目标定义要向其发送数据的边缘,以及投影配置定义将在边缘上提供的特定信息。 本指南提供了使用Real-time Customer Profile API处理边缘投影的详细说明,包括目标和配置。

快速入门

本指南中使用的API端点是Real-time Customer Profile API的一部分。 在继续操作之前,请查阅快速入门指南 ,以获取相关文档的链接、本文档中API调用示例的阅读指南,以及有关成功调用任何Experience Platform API所需标头的重要信息。

注意

包含有效负载(POST、PUT、PATCH)的请求需要Content-Type标头。 本文档中使用了多个Content-Type。 请特别注意示例调用中的标头,以确保对每个请求使用正确的Content-Type

投影目标

通过指定要发送数据的位置,可以将投影路由到一个或多个边缘。 创建的每个投影目标都有一个唯一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数组将返回空。

注意

此响应因空间而缩短,仅显示两个目标。

{
    "_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 (必需) 一个字符串数组,列出要将投影路由到的边。 可以包含以下一个或多个值:“OR1” — 美国西部,“VA5” — 美国东部,“NLD1” - EMEA。
ttl (必需) 指定投影过期。 接受的值范围:600至604800。 默认值:3600。
replicationPolicy (必需) 定义从集线器到边缘的数据复制行为。 支持的值:主动、被动。 默认值:反应。

响应

成功响应会返回新创建的边缘目标的详细信息,包括只读、系统生成的唯一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。

请求

以下请求更新了现有目标以包含第二个位置(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(未找到)。

投影配置

投影配置提供有关每个边缘上哪些数据可用的信息。 投影不会将完整的Experience Data Model (XDM)架构投影到边缘,而是仅提供该架构中的特定数据或字段。 贵组织可以为每个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关联的所有投影配置。 有关XDM及其在Platform中的角色的更多信息,请首先阅读XDM系统概述

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"
            },
        ]
    }
}

创建投影配置

您可以创建(POST)新的投影配置,以指示哪些XDM字段在边缘上可用。

API格式

POST /config/projections?schemaName={SCHEMA_NAME}
参数 描述
{SCHEMA_NAME} 与要访问的投影配置关联的架构类的名称。

请求

注意

创建配置的POST请求需要特定的Content-Type标头,如下所示。 使用错误的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 一个字符串,其中包含要复制到边缘的架构内的属性列表。 有关使用选择器的最佳实践,请参阅本文档的Selectors部分。
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

返回person.lastName字段和addresses数组中的所有元素。

{
  "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数组中每个元素的typecity字段值。 每个addresses元素中包含的所有其他子字段都会被过滤掉。

{
  "addresses": [
    {
      "type": "home",
      "city": {
        "name": "San Jose",
        "country": "United States"
      }
    },
    {
      "type": "work",
      "city": {
        "name": "San Jose",
        "country": "United States"
      }
    }
  ]
}

后续步骤

本指南向您展示了配置投影和目标所涉及的步骤,包括如何正确设置selector参数的格式。 您现在可以创建新的投影目标和配置,以满足您组织的需求。

在此页面上