連線 Data Landing Zone 使用流量服務API移至Adobe Experience Platform

上次更新： 2023-10-24

主題：
Sources
檢視有關此主題的更多資訊

建立對象：
Developer

User

Admin

Leader

重要

此頁面是特定的 Data Landing Zone 來源 Experience Platform中的聯結器。如需有關連線至 Data Landing Zone 目的地 聯結器，請參閱 Data Landing Zone 目的地檔案頁面.

Data Landing Zone 是安全的雲端檔案儲存設施，可將檔案匯入Adobe Experience Platform。資料會自動從 Data Landing Zone 七天之後。

本教學課程將逐步帶您瞭解如何建立 Data Landing Zone 來源連線使用 Flow Service API. 本教學課程也提供如何擷取您的 Data Landing Zone以及檢視和重新整理您的認證。

快速入門

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

來源：Experience Platform可讓您從各種來源擷取資料，同時使用Platform服務來建構、加標籤及增強傳入資料。
沙箱：Experience Platform提供的虛擬沙箱可將單一Platform執行個體分割成個別的虛擬環境，以利開發及改進數位體驗應用程式。

以下小節提供成功建立所需的其他資訊 Data Landing Zone 來源連線使用 Flow Service API。

本教學課程也要求您閱讀以下內容的指南： Platform API快速入門瞭解如何驗證平台API並解譯檔案中提供的範例呼叫。

擷取可用的登陸區域

使用API來存取的第一步 Data Landing Zone GET是向 /landingzone 的端點 Connectors API同時提供 type=user_drop_zone 做為請求標頭的一部分。

API格式

GET /data/foundation/connectors/landingzone?type=user_drop_zone

標頭	說明
`user_drop_zone`	此 `user_drop_zone` 型別可讓API將登陸區域容器與您可用的其他型別容器區分開來。

要求

以下請求會擷取現有的登陸區域。

curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/landingzone?type=user_drop_zone' \
  -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'

回應

下列回應會傳回登陸區域的資訊，包括其對應的資訊 containerName 和 containerTTL.

{
    "containerName": "dlz-user-container",
    "containerTTL": "7"
}

屬性	說明
`containerName`	擷取的登陸區域名稱。
`containerTTL`	登陸區域內套用至您資料的到期時間（以天為單位）。指定登陸區域中的任何專案都會在七天後刪除。

擷取 Data Landing Zone 認證

擷取認證 Data Landing Zone，向發出GET要求 /credentials 的端點 Connectors API。

API格式

GET /data/foundation/connectors/landingzone/credentials?type=user_drop_zone

要求

以下請求範例會擷取現有登陸區域的認證。

curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone' \
  -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' \

回應

下列回應會傳回您資料登陸區域的認證資訊，包括您目前的 SASToken， SASUri， storageAccountName和到期日。

{
    "containerName": "dlz-user-container",
    "SASToken": "sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
    "storageAccountName": "dlblobstore99hh25i3dflek",
    "SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
    "expiryDate": "2024-01-06"
}

屬性	說明
`containerName`	您的登陸區域的名稱。
`SASToken`	您登陸區域的共用存取權簽章Token。此字串包含授權請求所需的所有資訊。
`SASUri`	登陸區域的共用存取簽章URI。此字串是您正在接受驗證的登陸區域的URI及其對應的SAS權杖的組合，
`expiryDate`	您的SAS Token到期的日期。您必須在到期日之前重新整理權杖，才能繼續在您的應用程式中使用它來將資料上傳到資料登陸區域。如果您未在所述的到期日之前手動重新整理權杖，則會在執行GET認證呼叫時自動重新整理並提供新權杖。

更新 Data Landing Zone 認證

您可以更新 SASToken 向發出POST請求 /credentials 的端點 Connectors API。

API格式

POST /data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh

標頭	說明
`user_drop_zone`	此 `user_drop_zone` 型別可讓API將登陸區域容器與您可用的其他型別容器區分開來。
`refresh`	此 `refresh` 動作可讓您重設登陸區域認證，並自動產生新的 `SASToken`.

要求

以下請求會更新您的登陸區域認證。

curl -X POST \
  'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh' \
  -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' \

回應

以下回應會傳回您的已更新值 SASToken 和 SASUri.

{
    "containerName": "dlz-user-container",
    "SASToken": "sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
    "storageAccountName": "dlblobstore99hh25i3dflek",
    "SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
    "expiryDate": "2024-01-06"
}

探索登陸區域檔案結構和內容

您可以透過向以下網站發出GET請求，探索您的登陸區域的檔案結構和內容： connectionSpecs 的端點 Flow Service API。

API格式

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root

參數	說明
`{CONNECTION_SPEC_ID}`	與對應的連線規格ID Data Landing Zone. 此固定ID為： `26f526f2-58f4-4712-961d-e41bf1ccc0e8`.

要求

curl -X GET \
    'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=root' \
    -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}'

回應

成功的回應會傳回在查詢的目錄中找到的檔案和資料夾陣列。記下 path 要上傳之檔案的屬性，因為您必須在下一個步驟中提供該屬性以檢查其結構。

[
    {
        "type": "file",
        "name": "account.csv",
        "path": "dlz-user-container/account.csv",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "file",
        "name": "data8.csv",
        "path": "dlz-user-container/data8.csv",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "folder",
        "name": "userdata1",
        "path": "dlz-user-container/userdata1/",
        "canPreview": false,
        "canFetchSchema": false
    }
]

預覽登陸區域檔案結構和內容

若要檢查登入區域中的檔案結構，請在提供檔案路徑並輸入作為查詢引數的同時，執行GET要求。

API格式

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}

參數	說明	範例
`{CONNECTION_SPEC_ID}`	與對應的連線規格ID Data Landing Zone. 此固定ID為： `26f526f2-58f4-4712-961d-e41bf1ccc0e8`.
`{OBJECT_TYPE}`	您要存取的物件型別。	`file`
`{OBJECT}`	您要存取之物件的路徑和名稱。	`dlz-user-container/data8.csv`
`{FILE_TYPE}`	檔案的型別。	`delimited` `json` `parquet`
`{PREVIEW}`	布林值，定義是否支援檔案預覽。	`true` `false`

要求

curl -X GET \
    'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/data8.csv&fileType=delimited&preview=true' \
    -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}'

回應

成功的回應會傳回查詢檔案的結構，包括檔案名稱和資料型別。

{
    "format": "flat",
    "schema": {
        "columns": [
            {
                "name": "Id",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "FirstName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "LastName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "Email",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "Phone",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            }
        ]
    },
    "data": [
        {
            "Email": "rsmith@abc.com",
            "FirstName": "Richard",
            "Phone": "111111111",
            "Id": "12345",
            "LastName": "Smith"
        },
        {
            "Email": "morgan@bac.com",
            "FirstName": "Morgan",
            "Phone": "22222222222",
            "Id": "67890",
            "LastName": "Hart"
        }
    ]
}

使用 `determineProperties` 自動偵測檔案屬性資訊 Data Landing Zone

您可以使用 determineProperties 用於自動偵測檔案內容之屬性資訊的引數， Data Landing Zone 進行GET呼叫以探索來源的內容和結構時。

`determineProperties` 使用案例

下表概述您使用時可能遇到的不同情境 determineProperties 查詢引數或手動提供檔案的相關資訊。

`determineProperties`	`queryParams`	回應
True	不適用	如果 `determineProperties` 會提供作為查詢引數，然後就會進行檔案屬性偵測，而且回應會傳回新的 `properties` 包含檔案型別、壓縮型別和欄分隔符號相關資訊的金鑰。
不適用	True	如果檔案型別、壓縮型別和欄分隔符號的值是手動提供的，做為的一部分 `queryParams`，然後會用來產生結構，而相同的屬性會隨著回應傳回。
True	True	如果兩個選項同時完成，則會傳回錯誤。
不適用	不適用	如果兩個選項均未提供，則會傳回錯誤，因為無法取得回應的屬性。

API格式

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true

參數	說明	範例
`determineProperties`	此查詢引數允許 Flow Service 用於檢測檔案屬性相關資訊的API，包括檔案型別、壓縮型別和欄分隔符號的相關資訊。	`true`

要求

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/garageWeek/file1&preview=true&determineProperties=true' \
    -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}'

回應

成功的回應會傳回查詢檔案的結構，包括檔案名稱和資料型別，以及 properties 索引鍵，包含相關資訊 fileType， compressionType、和 columnDelimiter.

按一下我

{
    "properties": {
        "fileType": "delimited",
        "compressionType": "tarGzip",
        "columnDelimiter": "~"
    },
    "format": "flat",
    "schema": {
        "columns": [
            {
                "name": "id",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "firstName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "lastName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "email",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "birthday",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            }
        ]
    },
    "data": [
        {
            "birthday": "1313-0505-19731973",
            "firstName": "Yvonne",
            "lastName": "Thilda",
            "id": "100",
            "email": "Yvonne.Thilda@yopmail.com"
        },
        {
            "birthday": "1515-1212-19731973",
            "firstName": "Mary",
            "lastName": "Pillsbury",
            "id": "101",
            "email": "Mary.Pillsbury@yopmail.com"
        },
        {
            "birthday": "0505-1010-19751975",
            "firstName": "Corene",
            "lastName": "Joeann",
            "id": "102",
            "email": "Corene.Joeann@yopmail.com"
        },
        {
            "birthday": "2727-0303-19901990",
            "firstName": "Dari",
            "lastName": "Greenwald",
            "id": "103",
            "email": "Dari.Greenwald@yopmail.com"
        },
        {
            "birthday": "1717-0404-19651965",
            "firstName": "Lucy",
            "lastName": "Magdalen",
            "id": "199",
            "email": "Lucy.Magdalen@yopmail.com"
        }
    ]
}

屬性	說明
`properties.fileType`	查詢檔案的對應檔案型別。支援的檔案型別為： `delimited`， `json`、和 `parquet`.
`properties.compressionType`	用於查詢檔案的對應壓縮型別。支援的壓縮型別為： `bzip2` `gzip` `zipDeflate` `tarGzip` `tar`
`properties.columnDelimiter`	用於查詢檔案的對應欄分隔符號。任何單一字元值都是允許的欄分隔符號。預設值為逗號 `(,)`.

建立來源連線

來源連線會建立和管理與擷取資料的外部來源的連線。來源連線包含資料來源、資料格式以及建立資料流所需的來源連線ID等資訊。租使用者和組織專屬的來源連線例項。

POST若要建立來源連線，請向 /sourceConnections 的端點 Flow Service API。

API格式

POST /sourceConnections

要求

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
    -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": "Data Landing Zone source connection",
        "data": {
            "format": "delimited"
        },
        "params": {
            "path": "dlz-user-container/data8.csv"
        },
        "connectionSpec": {
            "id": "26f526f2-58f4-4712-961d-e41bf1ccc0e8",
            "version": "1.0"
        }
    }'

屬性	說明
`name`	您的名稱 Data Landing Zone 來源連線。
`data.format`	您要帶到Platform的資料格式。
`params.path`	您要帶到Platform的檔案路徑。
`connectionSpec.id`	與對應的連線規格ID Data Landing Zone. 此固定ID為： `26f526f2-58f4-4712-961d-e41bf1ccc0e8`.

回應

成功的回應會傳回唯一識別碼(id)。在下一個教學課程中，需要此ID才能建立資料流。

{
    "id": "f5b46949-8c8d-4613-80cc-52c9c039e8b9",
    "etag": "\"1400d460-0000-0200-0000-613be3520000\""
}

後續步驟

依照本教學課程，您已擷取 Data Landing Zone 認證，探索其檔案結構以尋找您要帶到Platform的檔案，並建立來源連線以開始將您的資料帶到Platform。您現在可以繼續進行下一個教學課程，您將在該課程中學習如何建立資料流，使用將雲端儲存空間資料帶入Platform Flow Service API.

連線 Data Landing Zone 使用流量服務API移至Adobe Experience Platform

快速入門

擷取可用的登陸區域

擷取 Data Landing Zone 認證

更新 Data Landing Zone 認證

探索登陸區域檔案結構和內容

預覽登陸區域檔案結構和內容

使用 `determineProperties` 自動偵測檔案屬性資訊 Data Landing Zone

`determineProperties` 使用案例

建立來源連線

後續步驟

此頁面上的

檢視下一個：

學習

檔案

社群

支援

資源

Adobe帳戶

Adobe

連線 Data Landing Zone 使用流量服務API移至Adobe Experience Platform

快速入門

擷取可用的登陸區域

擷取 Data Landing Zone 認證

更新 Data Landing Zone 認證

探索登陸區域檔案結構和內容

預覽登陸區域檔案結構和內容

使用 determineProperties 自動偵測檔案屬性資訊 Data Landing Zone

determineProperties 使用案例

建立來源連線

後續步驟

此頁面上的

檢視下一個：

學習

檔案

社群

支援

資源

Adobe帳戶

Adobe

使用 `determineProperties` 自動偵測檔案屬性資訊 Data Landing Zone

`determineProperties` 使用案例