邊緣投影配置和目標端點

為即時跨多個通道為客戶提供協調、一致且個人化的體驗，需要隨時提供適當的資料，並在變更時持續更新。 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語法鬆散。支援的語法概述如下，並提供其他範例以供參考。

支援的語法

使用逗號來選取多個欄位。因此請勿使用空格。
使用點符號來選取巢狀欄位。
- 例如，要選擇名為field的欄位，該欄位在名為foo的欄位內嵌，請使用選擇器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陣列中每個元素的type和city欄位值。每個addresses元素中包含的所有其他子欄位都被過濾掉。

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

後續步驟

本指南已向您顯示配置投影和目標所涉及的步驟，包括如何正確格式化selector參數。您現在可以根據組織的需求建立新的投影目的地和設定。

adobe.com上的資源

Omnichannel Personalization Subscription Revenue Customer Communications Ad Hoc Analysis Attribution Efficiency Tools

邊緣投影配置和目標端點

快速入門

投影目的地

列出所有目標

建立目標

檢視目標

更新目標

刪除目標

投影配置

列出所有投影配置

建立投影配置

選擇器

支援的語法

選擇器參數的範例

後續步驟

adobe.com上的資源

本頁內容

檢視下一個：

學習

說明文件

社群

技術支援

資源

Adobe帳戶

Adobe