此頁面專屬於 Data Landing Zone source Experience Platform中的聯結器。 如需有關連線至 Data Landing Zone 目的地 聯結器,請參閱 Data Landing Zone 目的地檔案頁面.
Data Landing Zone 是安全的雲端型檔案儲存設施,可將檔案帶入Adobe Experience Platform。 資料會自動從 Data Landing Zone 7天之後。
本教學課程將逐步引導您完成如何建立 Data Landing Zone 來源連線使用 Flow Service API. 本教學課程也提供如何擷取 Data Landing Zone以及檢視和重新整理您的認證。
本指南需要您實際瞭解下列Experience Platform元件:
以下小節提供成功建立所需的其他資訊 Data Landing Zone 來源連線使用 Flow Service API。
本教學課程也要求您閱讀以下專案的指南: Platform API快速入門 瞭解如何驗證Platform 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 type可讓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"
}
屬性 | 說明 |
---|---|
containerName |
您的登陸區域的名稱。 |
SASToken |
登陸區域的共用存取權簽章權杖。 此字串包含授權請求所需的所有資訊。 |
SASUri |
登陸區域的共用存取簽名URI。 此字串是URI的組合,包含您要驗證身分的登陸區域及其對應的SAS權杖。 |
您可以更新 SASToken
向發出POST要求 /credentials
的端點 Connectors API。
API格式
POST /data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh
標頭 | 說明 |
---|---|
user_drop_zone |
此 user_drop_zone type可讓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"
}
您可以透過向以下網站發出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.