此頁面是特定的 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 元件:
以下小節提供成功建立所需的其他資訊 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,向發出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認證呼叫時自動重新整理並提供新權杖。 |
您可以更新 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} |
檔案的型別。 |
|
{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 |
用於查詢檔案的對應壓縮型別。 支援的壓縮型別為:
|
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.