文件Experience Platform目的地指南

連線至檔案式電子郵件行銷目的地，並使用流量服務API啟用資料

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

建立對象：

  • 管理員
  • 使用者
IMPORTANT

  • 若要連線到目的地，您需要​ 檢視目的地 ​和​ 管理目的地 存取控制許可權。

  • 若要啟用資料，您需要​ 檢視目的地、啟用目的地、檢視設定檔 ​和​ 檢視區段 存取控制許可權。

  • 若要匯出​ 身分，您需要​ 檢視身分圖表 存取控制許可權。
    選取工作流程中反白的身分名稱空間，以啟用目的地的對象。 {width="100" modal="regular"}

閱讀存取控制總覽或連絡您的產品管理員以取得必要的許可權。

此教學課程示範如何使用流程服務API來建立檔案式電子郵件行銷目的地、建立資料流到您新建立的目的地，以及透過CSV檔案將資料匯出到您新建立的目的地。

TIP
若要瞭解如何使用Flow Service API啟用雲端儲存空間目的地的資料，請閱讀專用API教學課程。

本教學課程在所有範例中都使用Adobe Campaign目的地，但檔案式電子郵件行銷目的地的步驟相同。

概觀 — 建立目的地和啟用對象的步驟

如果您偏好使用Platform使用者介面連線到目的地並啟用資料，請參閱連線目的地和啟用對象資料到批次設定檔匯出目的地教學課程。

快速入門 get-started

本指南需要您深入了解下列 Adobe Experience Platform 元件：

  • Experience Data Model (XDM) System： Experience Platform用來組織客戶體驗資料的標準化架構。
  • Segmentation Service： Adobe Experience Platform Segmentation Service可讓您從Real-Time Customer Profile資料在Adobe Experience Platform中建立對象。
  • Sandboxes： Experience Platform提供的虛擬沙箱可將單一Platform執行個體分割成個別的虛擬環境，以利開發及改進數位體驗應用程式。

以下章節提供在Platform中啟用批次目的地資料所需的其他資訊。

收集必要的認證 gather-required-credentials

若要完成本教學課程中的步驟，您應準備好下列憑證，端視您要連線及啟用對象的目的地型別而定。

  • 針對Amazon S3連線： accessId，secretKey
  • 針對Amazon S3與Adobe Campaign的連線： accessId，secretKey
  • 對於SFTP連線： domain、port、username、password或sshKey （取決於連線至FTP位置的連線方法）
  • 針對Azure Blob連線： connectionString
NOTE
Amazon S3連線的認證accessId、secretKey與Adobe Campaign的Amazon S3連線的accessId、secretKey相同。

讀取範例 API 呼叫 reading-sample-api-calls

本教學課程提供範例API呼叫，示範如何格式化您的請求。 這些包括路徑、必要的標頭和正確格式化的請求承載。 此外，也提供 API 回應中傳回的範例 JSON。 如需檔案中所使用範例API呼叫慣例的詳細資訊，請參閱Experience Platform疑難排解指南中如何讀取範例API呼叫一節。

收集必要和選用標題的值 gather-values-headers

若要呼叫Platform API，您必須先完成驗證教學課程。 完成驗證教學課程會提供所有 Experience Platform API 呼叫中每個必要標頭的值，如下所示：

  • 授權：持有人{ACCESS_TOKEN}
  • x-api-key： {API_KEY}
  • x-gw-ims-org-id： {ORG_ID}

Experience Platform中的資源可以隔離到特定的虛擬沙箱。 在對Platform API的請求中，您可以指定將執行作業的沙箱名稱和ID。 這些是選用引數。

  • x-sandbox-name： {SANDBOX_NAME}
NOTE
如需Experience Platform中沙箱的詳細資訊，請參閱沙箱概觀檔案。

包含裝載(POST、PUT、PATCH)的所有請求都需要額外的媒體型別標頭：

  • Content-Type： application/json

API參考檔案 api-reference-documentation

在本教學課程中，您可以找到所有API作業的隨附參考檔案。 請參閱Adobe I/O🔗上的流程服務API檔案。 我們建議您同時使用本教學課程和API參考檔案。

取得可用目的地的清單 get-the-list-of-available-destinations

目的地步驟概述步驟1

首先，您必須決定要將資料啟動到的目的地。 首先，請執行呼叫以請求您可以連線並啟用對象的目標可用目的地清單。 對connectionSpecs端點執行下列GET要求，以傳回可用目的地的清單：

API格式

GET /connectionSpecs

要求

curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

回應

成功的回應包含可用目的地的清單及其唯一識別碼(id)。 儲存您計畫使用的目的地值，因為後續步驟需要它。 例如，如果您想要連線並將對象傳送至Adobe Campaign，請在回應中尋找下列程式碼片段：

{
    "id": "0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
  "name": "Adobe Campaign",
  ...
  ...
}

下表包含常用批次目的地的連線規格ID以供您參考：

目的地
連線規格ID
Adobe Campaign
0b23e41a-cb4a-4321-a78f-3b654f5d7d97
Oracle Eloqua
c1e44b6b-e7c8-404b-9031-58f0ef760604
Oracle Responsys
a5e28ddf-e265-426e-83a1-9d03a3a6822b
Salesforce Marketing Cloud
f599a5b3-60a7-4951-950a-cc4115c7ea27

連線到您的Experience Platform資料 connect-to-your-experience-platform-data

目的地步驟概述步驟2

接下來，您必須連線至您的Experience Platform資料，才能匯出設定檔資料，並在您偏好的目的地啟用該資料。 此包含兩個子步驟，如下所述。

  1. 首先，您必須透過設定基礎連線，執行呼叫以授權存取Experience Platform中的資料。
  2. 然後，使用基本連線ID執行另一個呼叫，您會在其中建立​ 來源連線，以建立與您Experience Platform資料的連線。

在Experience Platform中授權存取您的資料

API格式

POST /connections

要求

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Base connection to Experience Platform",
            "description": "This call establishes the connection to Experience Platform data",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            }
}'
屬性
說明
name
提供基礎連線至Experience PlatformProfile store的名稱。
description
您可以選擇提供基本連線的說明。
connectionSpec.id
使用Experience Platform設定檔存放區 - 8a9c3494-9708-43d7-ae3f-cda01e5030e1的連線規格識別碼。

回應

成功的回應包含基底連線的唯一識別碼(id)。 將此值儲存為建立來源連線之下一個步驟所需的值。

{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

連線到您的Experience Platform資料 connect-to-platform-data

API格式

POST /sourceConnections

要求

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Connecting to Profile store",
            "description": "Optional",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            },
            "baseConnectionId": "{BASE_CONNECTION_ID}",
            "data": {
                "format": "CSV",
                "schema": null
            },
            "params" : {}
}'
屬性
說明
name
提供來源連線與Experience PlatformProfile store的名稱。
description
您可以選擇提供來源連線的說明。
connectionSpec.id
使用Experience Platform設定檔存放區 - 8a9c3494-9708-43d7-ae3f-cda01e5030e1的連線規格識別碼。
baseConnectionId
使用您在上一步中取得的基本連線ID。
data.format
CSV是目前唯一支援的檔案匯出格式。

回應

成功回應傳回新建立的來源連線至Profile store的唯一識別碼(id)。 這可確認您已成功連線至您的Experience Platform資料。 將此值依後續步驟的需要儲存。

{
    "id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}

連線到批次目的地 connect-to-batch-destination

目的地步驟概述步驟3

在此步驟中，您會設定與所需批次雲端儲存空間或電子郵件行銷目的地的連線。 此包含兩個子步驟，如下所述。

  1. 首先，您必須透過設定基礎連線，執行呼叫以授權存取目的地平台。
  2. 然後，使用基本連線ID進行另一個呼叫，以建立​ 目標連線，這會指定儲存體帳戶中要傳送已匯出資料檔案的位置，以及要匯出的資料格式。

授權存取批次目的地 authorize-access-to-batch-destination

API格式

POST /connections

要求

下列要求會建立與Adobe Campaign目的地的基底連線。 根據您要將檔案匯出至(Amazon S3、SFTP、Azure Blob)的儲存位置，請保留適當的auth規格並刪除其他規格。

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "S3 Connection for Adobe Campaign",
    "description": "summer advertising campaign",
    "connectionSpec": {
        "id": "0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
        "version": "1.0"
    },
    "auth": {
        "specName": "S3",
        "params": {
            "accessId": "{ACCESS_ID}",
            "secretKey": "{SECRET_KEY}"
        }
    }
    "auth": {
        "specName": "SFTP with Password",
        "params": {
            "domain": "{DOMAIN}",
            "host": "{HOST}",
            "username": "{USERNAME}",
            "password": "{PASSWORD}"
        }
    }
    "auth": {
        "specName": "SFTP with SSH Key",
        "params": {
            "domain": "{DOMAIN}",
            "host": "{HOST}",
            "username": "{USERNAME}",
            "sshKey": "{SSH_KEY}"
        }
    }
    "auth": {
        "specName": "Azure Blob",
        "params": {
            "connectionString": "{AZURE_BLOB_CONNECTION_STRING}"
        }
    }
}'

請參閱下列請求範例，以連線至其他支援的批次雲端儲存空間及電子郵件行銷目的地。

連線到Amazon S3目的地的要求範例

下列要求會建立與Amazon S3目的地的基底連線。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connect to Amazon S3",
    "description": "summer advertising campaign",
    "connectionSpec": {
        "id": "4890fc95-5a1f-4983-94bb-e060c08e3f81",
        "version": "1.0"
    },
    "auth": {
        "specName": "Access Key",
        "params": {
            "s3AccessKey": "{AMAZON_S3_ACCESS_KEY}",
            "s3SecretKey": "{AMAZON_S3_SECRET_KEY}"
        }
    }
}'
連線到Azure Blob目的地的要求範例

下列要求會建立與Azure Blob目的地的基底連線。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connect to Azure Blob",
    "description": "Summer advertising campaign",
    "connectionSpec": {
        "id": "e258278b-a4cf-43ac-b158-4fa0ca0d948b",
        "version": "1.0"
    },
    "auth": {
        "specName": "ConnectionString",
        "params": {
            "connectionString": "{AZURE_BLOB_CONNECTION_STRING}"
        }
    }
}'
連線到Oracle Eloqua目的地的要求範例

下列要求會建立與Oracle Eloqua目的地的基底連線。 根據您要將檔案匯出到的儲存位置，保留適當的auth規格並刪除其他規格。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connect to Eloqua destination",
    "description": "summer advertising campaign",
    "connectionSpec": {
        "id": "c1e44b6b-e7c8-404b-9031-58f0ef760604",
        "version": "1.0"
    },
    "auth": {
        "specName": "SFTP with Password",
        "params": {
            "domain": "{DOMAIN}",
            "host": "{HOST}",
            "username": "{USERNAME}",
            "password": "{PASSWORD}"
        }
    }
    "auth": {
        "specName": "SFTP with SSH Key",
        "params": {
            "domain": "{DOMAIN}",
            "host": "{HOST}",
            "username": "{USERNAME}",
            "sshKey": "{SSH_KEY}"
        }
    }
}'
連線到Oracle Responsys目的地的要求範例

下列要求會建立與Oracle Responsys目的地的基底連線。 根據您要將檔案匯出到的儲存位置，保留適當的auth規格並刪除其他規格。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connect to Responsys destination",
    "description": "summer advertising campaign",
    "connectionSpec": {
        "id": "a5e28ddf-e265-426e-83a1-9d03a3a6822b",
        "version": "1.0"
    },
    "auth": {
        "specName": "SFTP with Password",
        "params": {
            "domain": "{DOMAIN}",
            "host": "{HOST}",
            "username": "{USERNAME}",
            "password": "{PASSWORD}"
        }
    }
    "auth": {
        "specName": "SFTP with SSH Key",
        "params": {
            "domain": "{DOMAIN}",
            "host": "{HOST}",
            "username": "{USERNAME}",
            "sshKey": "{SSH_KEY}"
        }
    }
}'
連線到Salesforce Marketing Cloud目的地的要求範例

下列要求會建立與Salesforce Marketing Cloud目的地的基底連線。 根據您要將檔案匯出到的儲存位置，保留適當的auth規格並刪除其他規格。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connect to Salesforce Marketing Cloud",
    "description": "summer advertising campaign",
    "connectionSpec": {
        "id": "f599a5b3-60a7-4951-950a-cc4115c7ea27",
        "version": "1.0"
    },
    "auth": {
        "specName": "SFTP with Password",
        "params": {
            "domain": "{DOMAIN}",
            "host": "{HOST}",
            "username": "{USERNAME}",
            "password": "{PASSWORD}"
        }
    }
    "auth": {
        "specName": "SFTP with SSH Key",
        "params": {
            "domain": "{DOMAIN}",
            "host": "{HOST}",
            "username": "{USERNAME}",
            "sshKey": "{SSH_KEY}"
        }
    }
}'
使用密碼目的地連線至SFTP的請求範例

以下請求會建立與SFTP目的地的基底連線。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connect to SFTP with password",
    "description": "summer advertising campaign",
    "connectionSpec": {
        "id": "64ef4b8b-a6e0-41b5-9677-3805d1ee5dd0",
        "version": "1.0"
    },
    "auth": {
        "specName": "Basic Authentication for sftp",
        "params": {
            "host": "{HOST}",
            "username": "{USERNAME}",
            "password": "{PASSWORD}"
        }
    }
}'
屬性
說明
name
提供批次目的地的基本連線名稱。
description
您可以選擇提供基本連線的說明。
connectionSpec.id
使用所需批次目的地的連線規格ID。 您在步驟取得可用目的地的清單中取得此識別碼。
auth.specname
表示目的地的驗證格式。 若要尋找您目的地的specName，請對連線規格端點🔗執行GET呼叫，提供您所要目的地的連線規格。 在回應中尋找引數authSpec.name。
例如，對於Adobe Campaign目的地，您可以使用任何S3、SFTP with Password或SFTP with SSH Key。
params
根據您連線的目的地，您必須提供不同的必要驗證引數。 針對Amazon S3連線，您必須提供Amazon S3儲存位置的存取ID和秘密金鑰。
若要找出您目的地所需的引數，請對連線規格端點🔗執行GET呼叫，提供您所要目的地的連線規格。 在回應中尋找引數authSpec.spec.required。

回應

成功的回應包含基底連線的唯一識別碼(id)。 將此值儲存為建立目標連線的下一個步驟所需的值。

{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

指定儲存位置和資料格式 specify-storage-location-data-format

Adobe Experience Platform以CSV個檔案的形式，匯出批次電子郵件行銷和雲端儲存目的地的資料。 在此步驟中，您可以決定要匯出檔案之儲存位置的路徑。

IMPORTANT
Adobe Experience Platform會自動分割匯出檔案，每個檔案為500萬筆記錄（列）。 每一列代表一個設定檔。
分割檔案名稱會附加一個數字，表示檔案是較大匯出的一部分，例如： filename.csv、filename_2.csv、filename_3.csv。

API格式

POST /targetConnections

要求

以下請求會建立與Adobe Campaign目的地的目標連線，以判斷匯出的檔案會停留在您的儲存位置。 根據您要將檔案匯出到的儲存位置，保留適當的params規格並刪除其他規格。

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "TargetConnection for Adobe Campaign",
    "description": "Connection to Adobe Campaign",
    "baseConnectionId": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
        "version": "1.0"
    },
    "data": {
        "format": "json",
        "schema": {
            "id": "1.0",
            "version": "1.0"
        }
    },
    "params": {
        "mode": "S3",
        "bucketName": "{BUCKET_NAME}",
        "path": "{FILEPATH}",
        "format": "CSV"
    }
    "params": {
        "mode": "AZURE_BLOB",
        "container": "{CONTAINER}",
        "path": "{FILEPATH}",
        "format": "CSV"
    }
    "params": {
        "mode": "FTP",
        "remotePath": "{REMOTE_PATH}",
        "format": "CSV"
    }
}'

請參閱下列請求範例，為其他支援的批次雲端儲存和電子郵件行銷目的地設定儲存位置。

設定Amazon S3目的地儲存位置的要求範例

以下請求會建立與Amazon S3目的地的目標連線，以判斷匯出的檔案會停留在您的儲存位置。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "TargetConnection for Amazon S3",
    "description": "Connection to Amazon S3",
    "baseConnectionId": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "4890fc95-5a1f-4983-94bb-e060c08e3f81",
        "version": "1.0"
    },
    "data": {
        "format": "json",
        "schema": {
            "id": "1.0",
            "version": "1.0"
        }
    },
    "params": {
        "mode": "S3",
        "bucketName": "{BUCKET_NAME}",
        "path": "{FILEPATH}",
        "format": "CSV"
    }
}'
設定Azure Blob目的地儲存位置的要求範例

以下請求會建立與Azure Blob目的地的目標連線，以判斷匯出的檔案會停留在您的儲存位置。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "TargetConnection for Azure Blob",
    "description": "Connection to Azure Blob",
    "baseConnectionId": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "e258278b-a4cf-43ac-b158-4fa0ca0d948b",
        "version": "1.0"
    },
    "data": {
        "format": "json",
        "schema": {
            "id": "1.0",
            "version": "1.0"
        }
    },
    "params": {
        "mode": "AZURE_BLOB",
        "container": "{CONTAINER}",
        "path": "{FILEPATH}",
        "format": "CSV"
    }
}'
設定Oracle Eloqua目的地儲存位置的要求範例

以下請求會建立與Oracle Eloqua目的地的目標連線，以判斷匯出的檔案會停留在您的儲存位置。 根據您要將檔案匯出到的儲存位置，保留適當的params規格並刪除其他規格。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "TargetConnection for Oracle Eloqua",
    "description": "Connection to Oracle Eloqua",
    "baseConnectionId": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "c1e44b6b-e7c8-404b-9031-58f0ef760604",
        "version": "1.0"
    },
    "data": {
        "format": "json",
        "schema": {
            "id": "1.0",
            "version": "1.0"
        }
    },
    "params": {
        "mode": "S3",
        "bucketName": "{BUCKET_NAME}",
        "path": "{FILEPATH}",
        "format": "CSV"
    }
    "params": {
        "mode": "FTP",
        "remotePath": "{REMOTE_PATH}",
        "format": "CSV"
    }
}'
設定Oracle Responsys目的地儲存位置的要求範例

以下請求會建立與Oracle Responsys目的地的目標連線，以判斷匯出的檔案會停留在您的儲存位置。 根據您要將檔案匯出到的儲存位置，保留適當的params規格並刪除其他規格。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "TargetConnection for Oracle Responsys",
    "description": "Connection to Oracle Responsys",
    "baseConnectionId": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "a5e28ddf-e265-426e-83a1-9d03a3a6822b",
        "version": "1.0"
    },
    "data": {
        "format": "json",
        "schema": {
            "id": "1.0",
            "version": "1.0"
        }
    },
    "params": {
        "mode": "S3",
        "bucketName": "{BUCKET_NAME}",
        "path": "{FILEPATH}",
        "format": "CSV"
    }
    "params": {
        "mode": "FTP",
        "remotePath": "{REMOTE_PATH}",
        "format": "CSV"
    }
}'
設定Salesforce Marketing Cloud目的地儲存位置的要求範例

以下請求會建立與Salesforce Marketing Cloud目的地的目標連線，以判斷匯出的檔案會停留在您的儲存位置。 根據您要將檔案匯出到的儲存位置，保留適當的params規格並刪除其他規格。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "TargetConnection for Salesforce Marketing Cloud",
    "description": "Connection to Salesforce Marketing Cloud",
    "baseConnectionId": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "f599a5b3-60a7-4951-950a-cc4115c7ea27",
        "version": "1.0"
    },
    "data": {
        "format": "json",
        "schema": {
            "id": "1.0",
            "version": "1.0"
        }
    },
    "params": {
        "mode": "S3",
        "bucketName": "{BUCKET_NAME}",
        "path": "{FILEPATH}",
        "format": "CSV"
    }
    "params": {
        "mode": "FTP",
        "remotePath": "{REMOTE_PATH}",
        "format": "CSV"
    }
}'
設定SFTP目的地儲存位置的請求範例

以下請求會建立與SFTP目的地的目標連線，以判斷匯出的檔案會著陸至您的儲存位置。

code language-shell 
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "TargetConnection for SFTP",
    "description": "Connection to SFTP",
    "baseConnectionId": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "64ef4b8b-a6e0-41b5-9677-3805d1ee5dd0",
        "version": "1.0"
    },
    "data": {
        "format": "json",
        "schema": {
            "id": "1.0",
            "version": "1.0"
        }
    },
    "params": {
        "mode": "FTP",
        "remotePath": "{REMOTE_PATH}",
    }
}'
屬性
說明
name
提供批次目的地的目標連線名稱。
description
您可以選擇提供目標連線的說明。
baseConnectionId
使用您在上述步驟中建立之基本連線的ID。
connectionSpec.id
使用所需批次目的地的連線規格ID。 您在步驟取得可用目的地的清單中取得此識別碼。
params
視您連線的目的地而定，您必須為儲存位置提供不同的必要引數。 針對Amazon S3連線，您必須提供Amazon S3儲存位置的存取ID和秘密金鑰。
若要找出您目的地所需的引數，請對連線規格端點🔗執行GET呼叫，提供您所要目的地的連線規格。 在回應中尋找引數targetSpec.spec.required。
params.mode
視您目的地支援的模式而定，您必須在此處提供不同的值。 若要找出您目的地所需的引數，請對連線規格端點🔗執行GET呼叫，提供您所需目的地的連線規格。 在回應中尋找引數targetSpec.spec.properties.mode.enum，並選取所要的模式。
params.bucketName
對於S3連線，請提供要匯出檔案的儲存貯體名稱。
params.path
對於S3連線，請在要匯出檔案的儲存位置中提供檔案路徑。
params.format
CSV是目前唯一支援的檔案匯出型別。

回應

成功的回應會傳回新建立之目標連線到批次目的地的唯一識別碼(id)。 視需要在後續步驟中儲存此值。

{
    "id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}

建立資料流 create-dataflow

目的地步驟概述步驟4

使用您在上一步中取得的流量規格、來源連線及目標連線ID，您現在可以在Experience Platform資料與匯出資料檔案的目的地之間建立資料流。 將此步驟視為建構管道，稍後資料會透過管道在Experience Platform和您想要的目的地之間流動。

若要建立資料流，請執行POST請求，如下所示，同時在裝載中提供下列提及的值。

API格式

POST /flows

要求

curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d  '{

        "name": "activate audiences to Adobe Campaign",
        "description": "This operation creates a dataflow which we will later use to activate audiences to Adobe Campaign",
        "flowSpec": {
            "id": "{FLOW_SPEC_ID}",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "{SOURCE_CONNECTION_ID}"
        ],
        "targetConnectionIds": [
            "{TARGET_CONNECTION_ID}"
        ],
        "transformations": [
            {
                "name": "GeneralTransform",
                "params": {
                    "segmentSelectors": {
                        "selectors": []
                    },
                    "profileSelectors": {
                        "selectors": []
                    }
                }
            }
        ]
    }
屬性
說明
name
為您正在建立的資料流命名。
description
您可以選擇為資料流提供說明。
flowSpec.Id
使用您要連線之批次目的地的流程規格ID。 若要擷取流程規格ID，請對flowspecs端點執行GET作業，如流程規格API參考檔案所示。 在回應中，尋找upsTo並複製您要連線之批次目的地的對應ID。 例如，若為Adobe Campaign，尋找upsToCampaign並複製id引數。
sourceConnectionIds
使用您在步驟連線至您的Experience Platform資料中取得的來源連線識別碼。
targetConnectionIds
使用您在步驟連線到批次目的地中取得的目標連線識別碼。
transformations
在下一步中，您會將要啟用的對象和設定檔屬性填入此區段中。

下表包含常用批次目的地的流量規格ID以供您參考：

目的地
流量規格ID
所有雲端儲存空間目的地(Amazon S3、SFTP、Azure Blob)和Oracle Eloqua
71471eba-b620-49e4-90fd-23f1fa0174d8
Oracle Responsys
51d675ce-e270-408d-91fc-22717bdf2148
Salesforce Marketing Cloud
493b2bd6-26e4-4167-ab3b-5e910bba44f0

回應

成功的回應傳回新建立的資料流和etag的識別碼(id)。 視需要在下一個步驟記下這兩個值，以啟動對象並匯出資料檔案。

{
    "id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
    "etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}

啟用新目的地的資料 activate-data

目的地步驟概述步驟5

建立所有連線和資料流後，您現在可以將設定檔資料啟動到目的地平台。 在此步驟中，您可以選取要匯出至目的地的對象和設定檔屬性。

您也可以決定匯出檔案的檔案命名格式，以及哪些屬性應該用作重複資料刪除索引鍵或必要屬性。 在此步驟中，您也可以決定傳送資料至目的地的排程。

若要將對象啟用至您的新目的地，您必須執行JSONPATCH操作，類似於以下範例。 您可以在一次呼叫中啟用多個對象和設定檔屬性。 若要深入瞭解JSONPATCH，請參閱RFC規格。

API格式

PATCH /flows

要求

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
    {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the audience that you are activating",
                "description": "Description of the audience that you are activating",
                "id": "{SEGMENT_ID}",
                "filenameTemplate": "%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%",
                "exportMode": "DAILY_FULL_EXPORT",
                "schedule": {
                    "frequency": "ONCE",
                    "startDate": "2021-12-20",
                    "startTime": "17:00"
                }
            }
        }
    },
{
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the audience that you are activating",
                "description": "Description of the audience that you are activating",
                "id": "{SEGMENT_ID}",
                "filenameTemplate": "%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%",
                "exportMode": "DAILY_FULL_EXPORT",
                "schedule": {
                    "frequency": "ONCE",
                    "triggerType": "SCHEDULED",
                    "startDate": "2021-12-20",
                    "startTime": "17:00"
                },
            }
        }
    },
{
        "op": "add",
        "path": "/transformations/0/params/profileSelectors/selectors/-",
        "value": {
            "type": "JSON_PATH",
            "value": {
                "path": "{PROFILE_ATTRIBUTE}"
            }
        }
    }
]
屬性
說明
{DATAFLOW_ID}
在URL中，使用您在上一步建立的資料流ID。
{ETAG}

從上一步驟中的回應取得{ETAG}，建立資料流。 上一步驟中的回應格式已逸出引號。 您必須在請求標頭中使用未逸出的值。 請參閱下列範例：

  • 回應範例： "etag":""7400453a-0000-1a00-0000-62b1c7a90000""
  • 要在您的請求中使用的值： "etag": "7400453a-0000-1a00-0000-62b1c7a90000"

每次成功更新資料流時，etag值都會更新。

{SEGMENT_ID}
提供您要匯出至此目的地的對象ID。 若要擷取您要啟動之對象的對象ID，請參閱Experience Platform API參考中的擷取對象定義。
{PROFILE_ATTRIBUTE}
例如, "person.lastName"
op
用於定義更新資料流所需動作的操作呼叫。 作業包括： add、replace和remove。 若要將對象新增至資料流，請使用add作業。
path
定義要更新的流程部分。 將對象新增至資料流時，請使用範例中指定的路徑。
value
您想要用來更新引數的新值。
id
指定您要新增至目的地資料流的對象ID。
name
選擇性。 指定您要新增至目的地資料流的對象名稱。 請注意，此欄位並非必填欄位，您可以在不提供名稱的情況下成功將對象新增至目的地資料流。
filenameTemplate

此欄位會決定匯出至目的地之檔案的檔案名稱格式。
下列選項可供使用：

  • %DESTINATION_NAME%：必要。 匯出的檔案包含目的地名稱。
  • %SEGMENT_ID%：必要。 匯出的檔案包含匯出對象的ID。
  • %SEGMENT_NAME%：選擇性。 匯出的檔案包含匯出對象的名稱。
  • DATETIME(YYYYMMdd_HHmmss)或%TIMESTAMP%：選擇性。 選取這兩個選項之一，讓您的檔案包含Experience Platform產生檔案的時間。
  • custom-text：選擇性。 將此預留位置取代為您要在檔案名稱結尾附加的任何自訂文字。

如需設定檔案名稱的詳細資訊，請參閱批次目的地啟動教學課程中的設定檔案名稱一節。

exportMode
強制。 選取"DAILY_FULL_EXPORT"或"FIRST_FULL_THEN_INCREMENTAL"。 如需有關這兩個選項的詳細資訊，請參閱批次目的地啟動教學課程中的匯出完整檔案和匯出增量檔案。
startDate
選取對象應開始將設定檔匯出至您的目的地的日期。
frequency

強制。

  • 對於"DAILY_FULL_EXPORT"匯出模式，您可以選取ONCE或DAILY。
  • 對於"FIRST_FULL_THEN_INCREMENTAL"匯出模式，您可以選取"DAILY"、"EVERY_3_HOURS"、"EVERY_6_HOURS"、"EVERY_8_HOURS"、"EVERY_12_HOURS"。
triggerType

僅適用於​ 批次目的地。 只有在frequency選取器中選取"DAILY_FULL_EXPORT"模式時才需要此欄位。
必要。

  • 選取"AFTER_SEGMENT_EVAL"讓啟動工作在每日平台批次細分工作完成後立即執行。 這可確保在啟動工作執行時，最新的設定檔會匯出至您的目的地。
  • 選取"SCHEDULED"讓啟動工作以固定時間執行。 這可確保Experience Platform設定檔資料每天在同一時間匯出，但您匯出的設定檔可能不是最新的，這取決於批次細分工作是否在啟動工作開始之前完成。 選取此選項時，您也必須新增startTime以指示UTC中應該進行每日匯出的時間。
endDate
僅適用於​ 批次目的地。 只有在批次檔案匯出目的地(例如Amazon S3、SFTP或Azure Blob)中將對象新增至資料流時，才需要此欄位。
在選取"exportMode":"DAILY_FULL_EXPORT"和"frequency":"ONCE"時不適用。
設定對象成員停止匯出至目的地的日期。
startTime
僅適用於​ 批次目的地。 只有在批次檔案匯出目的地(例如Amazon S3、SFTP或Azure Blob)中將對象新增至資料流時，才需要此欄位。
必要。 選取包含對象成員的檔案應該產生並匯出至您的目的地的時間。
TIP
請參閱更新資料流中的對象元件，瞭解如何更新匯出對象的各種元件（檔案名稱範本、匯出時間等）。

回應

尋找202接受的回應。 未傳回任何回應內文。 若要驗證要求是否正確，請參閱下一步驗證資料流。

驗證資料流 validate-dataflow

目的地步驟概述步驟6

在教學課程的最後一步，您應該驗證對象和設定檔屬性是否確實已正確對應至資料流。

若要驗證，請執行以下的GET要求：

API格式

GET /flows

要求

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"'
  • {DATAFLOW_ID}：使用上一步驟的資料流。
  • {ETAG}：使用上一步驟的etag。

回應

傳回的回應應包含您在上一步中提交的對象和設定檔屬性，並將其納入transformations引數。 回應中的範例transformations引數可能如下所示：

"transformations":[
   {
      "name":"GeneralTransform",
      "params":{
         "profileSelectors":{
            "selectors":[
               {
                  "type":"JSON_PATH",
                  "value":{
                     "path":"homeAddress.countryCode",
                     "operator":"EXISTS",
                     "mapping":{
                        "sourceType":"text/x.schema-path",
                        "source":"homeAddress.countryCode",
                        "destination":"homeAddress.countryCode",
                        "identity":false,
                        "primaryIdentity":false,
                        "functionVersion":0,
                        "copyModeMapping":false,
                        "sourceAttribute":"homeAddress.countryCode",
                        "destinationXdmPath":"homeAddress.countryCode"
                     }
                  }
               },
               {
                  "type":"JSON_PATH",
                  "value":{
                     "path":"person.name.firstName",
                     "operator":"EXISTS",
                     "mapping":{
                        "sourceType":"text/x.schema-path",
                        "source":"person.name.firstName",
                        "destination":"person.name.firstName",
                        "identity":false,
                        "primaryIdentity":false,
                        "functionVersion":0,
                        "copyModeMapping":false,
                        "sourceAttribute":"person.name.firstName",
                        "destinationXdmPath":"person.name.firstName"
                     }
                  }
               },
               {
                  "type":"JSON_PATH",
                  "value":{
                     "path":"person.name.lastName",
                     "operator":"EXISTS",
                     "mapping":{
                        "sourceType":"text/x.schema-path",
                        "source":"person.name.lastName",
                        "destination":"person.name.lastName",
                        "identity":false,
                        "primaryIdentity":false,
                        "functionVersion":0,
                        "copyModeMapping":false,
                        "sourceAttribute":"person.name.lastName",
                        "destinationXdmPath":"person.name.lastName"
                     }
                  }
               },
               {
                  "type":"JSON_PATH",
                  "value":{
                     "path":"personalEmail.address",
                     "operator":"EXISTS",
                     "mapping":{
                        "sourceType":"text/x.schema-path",
                        "source":"personalEmail.address",
                        "destination":"personalEmail.address",
                        "identity":false,
                        "primaryIdentity":false,
                        "functionVersion":0,
                        "copyModeMapping":false,
                        "sourceAttribute":"personalEmail.address",
                        "destinationXdmPath":"personalEmail.address"
                     }
                  }
               },
               {
                  "type":"JSON_PATH",
                  "value":{
                     "path":"segmentMembership.status",
                     "operator":"EXISTS",
                     "mapping":{
                        "sourceType":"text/x.schema-path",
                        "source":"segmentMembership.status",
                        "destination":"segmentMembership.status",
                        "identity":false,
                        "primaryIdentity":false,
                        "functionVersion":0,
                        "copyModeMapping":false,
                        "sourceAttribute":"segmentMembership.status",
                        "destinationXdmPath":"segmentMembership.status"
                     }
                  }
               }
            ],
            "mandatoryFields":[
               "person.name.firstName",
               "person.name.lastName"
            ],
            "primaryFields":[
               {
                  "fieldType":"ATTRIBUTE",
                  "attributePath":"personalEmail.address"
               }
            ]
         },
         "segmentSelectors":{
            "selectors":[
               {
                  "type":"PLATFORM_SEGMENT",
                  "value":{
                     "id":"9f7d37fd-7039-4454-94ef-2b0cd6c3206a",
                     "name":"Interested in Mountain Biking",
                     "filenameTemplate":"%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%",
                     "exportMode":"DAILY_FULL_EXPORT",
                     "schedule":{
                        "frequency":"ONCE",
                        "startDate":"2021-12-20",
                        "startTime":"17:00"
                     },
                     "createTime":"1640016962",
                     "updateTime":"1642534355"
                  }
               },
               {
                  "type":"PLATFORM_SEGMENT",
                  "value":{
                     "id":"25768be6-ebd5-45cc-8913-12fb3f348613",
                     "name":"Loyalty Segment",
                     "filenameTemplate":"%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%",
                     "exportMode":"FIRST_FULL_THEN_INCREMENTAL",
                     "schedule":{
                        "frequency":"EVERY_6_HOURS",
                        "startDate":"2021-12-22",
                        "endDate":"2021-12-31",
                        "startTime":"17:00"
                     },
                     "createTime":"1640016962",
                     "updateTime":"1642534355"
                  }
               }
            ]
         }
      }
   }
]

API錯誤處理 api-error-handling

本教學課程中的API端點會遵循一般Experience PlatformAPI錯誤訊息原則。 如需解譯錯誤回應的詳細資訊，請參閱Platform疑難排解指南中的API狀態碼和要求標頭錯誤。

後續步驟 next-steps

依照本教學課程中的指示，您已成功將Platform連線至其中一個慣用的檔案式電子郵件行銷目的地，並設定資料流至個別目的地以匯出資料檔案。 現在，傳出資料可用於電子郵件行銷活動、目標定位廣告和許多其他使用案例的目的地。 如需詳細資訊，請參閱下列頁面，例如如何使用流量服務API編輯現有資料流：

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6