加密的資料擷取
建立對象:
- 開發人員
您可以使用雲端儲存批次來源,將加密資料檔案擷取至Adobe Experience Platform。 透過加密的資料擷取,您可以運用非對稱加密機制,將批次資料安全地傳輸至Experience Platform。 目前,支援的非對稱加密機製為PGP和GPG。
加密的資料擷取程式如下:
- 使用Experience Platform API建立加密金鑰組。 加密金鑰組由私密金鑰和公開金鑰組成。 建立後,您可以複製或下載公開金鑰,以及其對應的公開金鑰ID和到期時間。 在此過程中,私密金鑰將由Experience Platform儲存在安全的儲存庫中。 注意: 回應中的公開金鑰是Base64編碼的,在使用之前必須先解碼。
- 使用公開金鑰來加密您要擷取的資料檔案。
- 將加密檔案放入雲端儲存空間。
- 加密檔案準備就緒後,為您的雲端儲存空間來源建立來源連線和資料流。 在流程建立步驟期間,您必須提供
encryption
引數並包含您的公開金鑰ID。 - Experience Platform會從安全儲存庫中擷取私密金鑰,以在擷取資料時解密資料。
本檔案提供如何產生加密金鑰組以加密您的資料,以及使用雲端儲存空間來源將加密的資料擷取到Experience Platform的步驟。
快速入門
本教學課程需要您實際瞭解下列Adobe Experience Platform元件:
使用Experience Platform API
如需如何成功呼叫Experience Platform API的詳細資訊,請參閱Experience Platform API快速入門指南。
加密檔案支援的副檔名
加密檔案支援的副檔名清單為:
- .csv
- .tsv
- .json
- .parquet
- .csv.gpg
- .tsv.gpg
- .json.gpg
- .parquet.gpg
- .csv.pgp
- .tsv.pgp
- .json.pgp
- .parquet.pgp
- .gpg
- .pgp
建立加密金鑰組
將加密資料擷取至Experience Platform的第一步,是對Connectors API的/encryption/keys
端點發出POST要求,以建立您的加密金鑰組。
API格式
POST /data/foundation/connectors/encryption/keys
要求
下列要求會使用PGP加密演演算法產生加密金鑰組。
curl -X POST \
'https://platform.adobe.io/data/foundation/connectors/encryption/keys' \
-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": "acme-encryption",
"encryptionAlgorithm": "PGP",
"params": {
"passPhrase": "{{PASSPHRASE}}"
}
}'
name
encryptionAlgorithm
PGP
和GPG
。params.passPhrase
回應
成功的回應會傳回Base64編碼的公開金鑰、公開金鑰ID,以及金鑰的到期時間。 到期時間會自動設定為產生金鑰日期後的180天。 到期時間目前無法設定。
{
"publicKey": "{PUBLIC_KEY}",
"publicKeyId": "{PUBLIC_KEY_ID}",
"expiryTime": "1684843168"
}
publicKey
publicKeyId
expiryTime
擷取加密金鑰
若要擷取您組織中的所有加密金鑰,請向/encryption/keys
endpoit=nt發出GET請求。
API格式
GET /data/foundation/connectors/encryption/keys
要求
以下請求會擷取貴組織中的所有加密金鑰。
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/encryption/keys' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'x-api-key: {{API_KEY}}' \
-H 'x-gw-ims-org-id: {{ORG_ID}}' \
回應
成功的回應會傳回您的加密演演算法、名稱、公開金鑰、公開金鑰ID、金鑰型別,以及金鑰的對應到期時間。
{
"encryptionAlgorithm": "{ENCRYPTION_ALGORITHM}",
"name": "{NAME}",
"publicKeyId": "{PUBLIC_KEY_ID}",
"publicKey": "{PUBLIC_KEY}",
"keyType": "{KEY_TYPE}",
"expiryTime": "{EXPIRY_TIME}"
}
依ID擷取加密金鑰
若要擷取一組特定的加密金鑰,請向/encryption/keys
端點發出GET要求,並提供您的公開金鑰ID作為標頭引數。
API格式
GET /data/foundation/connectors/encryption/keys/{PUBLIC_KEY_ID}
要求
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/encryption/keys/{publicKeyId}' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'x-api-key: {{API_KEY}}' \
-H 'x-gw-ims-org-id: {{ORG_ID}}' \
回應
成功的回應會傳回您的加密演演算法、名稱、公開金鑰、公開金鑰ID、金鑰型別,以及金鑰的對應到期時間。
{
"encryptionAlgorithm": "{ENCRYPTION_ALGORITHM}",
"name": "{NAME}",
"publicKeyId": "{PUBLIC_KEY_ID}",
"publicKey": "{PUBLIC_KEY}",
"keyType": "{KEY_TYPE}",
"expiryTime": "{EXPIRY_TIME}"
}
建立客戶自控金鑰組
您可以選擇建立簽署驗證金鑰組,以簽署並擷取您的加密資料。
在此階段,您必須產生自己的私密金鑰和公開金鑰組合,然後使用您的私密金鑰簽署您的加密資料。 接下來,您必須在Base64中編碼您的公開金鑰,然後將其共用至Experience Platform,以便Experience Platform驗證您的簽名。
將公開金鑰分享至Experience Platform
若要共用您的公開金鑰,請提供您的加密演演算法和Base64編碼的公開金鑰時,對/customer-keys
端點提出POST要求。
API格式
POST /data/foundation/connectors/encryption/customer-keys
要求
curl -X POST \
'https://platform.adobe.io/data/foundation/connectors/encryption/customer-keys' \
-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": "acme-sign-verification-keys"
"encryptionAlgorithm": {{ENCRYPTION_ALGORITHM}},
"publicKey": {{BASE_64_ENCODED_PUBLIC_KEY}},
"params": {
"passPhrase": {{PASS_PHRASE}}
}
}'
encryptionAlgorithm
PGP
和GPG
。publicKey
回應
{
"publicKeyId": "e31ae895-7896-469a-8e06-eb9207ddf1c2"
}
publicKeyId
擷取客戶管理的金鑰組
若要擷取您的客戶自控金鑰,請向/customer-keys
端點發出GET請求。
API格式
GET /data/foundation/connectors/encryption/customer-keys
要求
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/encryption/customer-keys' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'x-api-key: {{API_KEY}}' \
-H 'x-gw-ims-org-id: {{ORG_ID}}' \
回應
[
{
"encryptionAlgorithm": "{ENCRYPTION_ALGORITHM}",
"name": "{NAME}",
"publicKeyId": "{PUBLIC_KEY_ID}",
"publicKey": "{PUBLIC_KEY}",
"keyType": "{KEY_TYPE}",
}
]
使用Flow Service API將您的雲端儲存空間來源連線至Experience Platform
擷取加密金鑰組後,您現在可以繼續並為雲端儲存空間來源建立來源連線,並將加密資料帶入Experience Platform。
首先,您必須建立基礎連線,以針對Experience Platform驗證您的來源。 若要建立基礎連線並驗證您的來源,請從下列清單中選取您要使用的來源:
建立基礎連線後,您必須遵循教學課程中概述的步驟,針對建立雲端儲存空間來源的來源連線,以建立來源連線、目標連線和對應。
為加密的資料建立資料流
若要建立資料流,請對Flow Service API的/flows
端點提出POST要求。 若要內嵌加密的資料,您必須將encryption
區段新增至transformations
屬性,並包含在先前步驟中建立的publicKeyId
。
API格式
POST /flows
要求
以下請求會建立資料流,以擷取雲端儲存空間的加密資料。
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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": "ACME Customer Data",
"description": "ACME Customer Data (Encrypted)",
"flowSpec": {
"id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
"version": "1.0"
},
"sourceConnectionIds": [
"655f7c1b-1977-49b3-a429-51379ecf0e15"
],
"targetConnectionIds": [
"de688225-d619-481c-ae3b-40c250fd7c79"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "6b6e24213dbe4f57bd8207d21034ff03",
"mappingVersion":"0"
}
},
{
"name": "Encryption",
"params": {
"publicKeyId":"311ef6f8-9bcd-48cf-a9e9-d12c45fb7a17"
}
}
],
"scheduleParams": {
"startTime": "1675793392",
"frequency": "once"
}
}'
flowSpec.id
sourceConnectionIds
targetConnectionIds
transformations[x].params.mappingId
transformations.name
Encryption
作為資料流的其他轉換引數。transformations[x].params.publicKeyId
scheduleParams.startTime
scheduleParams.frequency
once
、minute
、hour
、day
或week
。scheduleParams.interval
once
時不需要間隔,其他頻率值應該大於或等於15
。回應
成功的回應會傳回您加密資料之新建立資料流的識別碼(id
)。
{
"id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
"etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}
要求
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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": "ACME Customer Data (with Sign Verification)",
"description": "ACME Customer Data (with Sign Verification)",
"flowSpec": {
"id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
"version": "1.0"
},
"sourceConnectionIds": [
"655f7c1b-1977-49b3-a429-51379ecf0e15"
],
"targetConnectionIds": [
"de688225-d619-481c-ae3b-40c250fd7c79"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "6b6e24213dbe4f57bd8207d21034ff03",
"mappingVersion":"0"
}
},
{
"name": "Encryption",
"params": {
"publicKeyId":"311ef6f8-9bcd-48cf-a9e9-d12c45fb7a17",
"signVerificationKeyId":"e31ae895-7896-469a-8e06-eb9207ddf1c2"
}
}
],
"scheduleParams": {
"startTime": "1675793392",
"frequency": "once"
}
}'
params.signVerificationKeyId
回應
成功的回應會傳回您加密資料之新建立資料流的識別碼(id
)。
{
"id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
"etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}
刪除加密金鑰
若要刪除您的加密金鑰,請向/encryption/keys
端點提出DELETE要求,並提供您的公開金鑰ID作為標頭引數。
API格式
DELETE /data/foundation/connectors/encryption/keys/{PUBLIC_KEY_ID}
要求
curl -X DELETE \
'https://platform.adobe.io/data/foundation/connectors/encryption/keys/{publicKeyId}' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'x-api-key: {{API_KEY}}' \
-H 'x-gw-ims-org-id: {{ORG_ID}}' \
回應
成功的回應會傳回HTTP狀態204 (無內容)和空白內文。
驗證加密金鑰
若要驗證您的加密金鑰,請向/encryption/keys/validate/
端點發出GET要求,並提供您要驗證為標頭引數的公開金鑰ID。
GET /data/foundation/connectors/encryption/keys/validate/{PUBLIC_KEY_ID}
要求
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/encryption/keys/validate/{publicKeyId}' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'x-api-key: {{API_KEY}}' \
-H 'x-gw-ims-org-id: {{ORG_ID}}' \
回應
成功的回應會傳回確認ID有效或無效的訊息。
有效的公開金鑰識別碼傳回Active
狀態以及您的公開金鑰識別碼。
{
"publicKeyId": "{PUBLIC_KEY_ID}",
"status": "Active"
}
無效的公開金鑰識別碼傳回Expired
狀態以及您的公開金鑰識別碼。
{
"publicKeyId": "{PUBLIC_KEY_ID}",
"status": "Expired"
}
週期性內嵌的限制
加密的資料擷取不支援在來源中擷取循環或多層資料夾。 所有加密的檔案都必須包含在單一資料夾中。 也不支援在單一來源路徑中包含多個資料夾的萬用字元。
以下是支援的資料夾結構範例,其中來源路徑為/ACME-customers/*.csv.gpg
。
在此案例中,粗體的檔案會擷取到Experience Platform中。
-
ACME — 客戶
- 檔案1.csv.gpg
- File2.json.gpg
- 檔案3.csv.gpg
- File4.json
- 檔案5.csv.gpg
以下是來源路徑為/ACME-customers/*
的不支援資料夾結構範例。
在此案例中,流程執行將失敗,並傳回錯誤訊息,指出無法從來源複製資料。
-
ACME — 客戶
-
File1.csv.gpg
-
File2.json.gpg
-
子資料夾1
- File3.csv.gpg
- File4.json.gpg
- File5.csv.gpg
-
-
ACME忠誠度
- File6.csv.gpg
後續步驟
依照此教學課程,您已為雲端儲存空間資料建立加密金鑰組,並使用Flow Service API為資料流擷取加密資料。 如需資料流完整性、錯誤和量度的狀態更新,請參閱使用 Flow Service API監視資料流的指南。