透過來源連接器和API收集通訊協定資料

Flow Service 用於收集和集中Adobe Experience Platform內不同來源的客戶資料。該服務提供用戶介面和REST風格的API，所有支援的源都可從中連接。

本教學課程涵蓋從協力廠商通訊協定應用程式擷取資料，並透過來源連接 Platform 器和 Flow Service API將其內嵌至其中的步驟。

快速入門

本教程要求您通過有效的基本連接和要導入的檔案（包括表的路徑和結構）來訪問協 Platform議系統。如果您沒有此資訊，請先參閱教學課程，了解如何使用Flow Service API來探索通訊協定系統，然後再嘗試本教學課程。

體驗資料模型(XDM)系統:Experience Platform組織客戶體驗資料的標準化架構。
- 架構構成基礎:瞭解XDM架構的基本建置區塊，包括架構組合的主要原則和最佳實務。
- 架構註冊開發人員指南:包含您必須知道的重要資訊，以便成功執行對架構註冊表API的呼叫。這包括您 {TENANT_ID}的「容器」概念，以及提出要求所需的標題（請特別注意「接受」標題及其可能的值）。
目錄服務:目錄是記錄資料位置和世系的系統 Experience Platform。
批處理提取:「批次擷取API」可讓您將資料擷取為 Experience Platform 批次檔案。
沙盒: Experience Platform 提供虛擬沙盒，可將單一執行個體分 Platform 割為不同的虛擬環境，以協助開發和發展數位體驗應用程式。

以下各節提供您需要瞭解的其他資訊，以便使用 Flow Service API成功連線至通訊協定應用程式。

讀取範例API呼叫

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

收集必要標題的值

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

Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {IMS_ORG}

中的所有資 Experience Platform源(包括屬於這些資源 Flow Service)都隔離到特定的虛擬沙盒。對API的所 Platform 有請求都需要一個標題，該標題會指定要在中執行的操作的沙盒名稱：

x-sandbox-name: {SANDBOX_NAME}

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

Content-Type: application/json

建立源連接

您可以對 Flow Service API提出POST要求，以建立來源連線。源連接由連接ID、源資料檔案的路徑和連接規範ID組成。

要建立源連接，還必須為資料格式屬性定義枚舉值。

對基於檔案的連接器使用以下枚舉值：

Data.format	列舉值
分隔檔案	`delimited`
JSON檔案	`json`
拼花檔案	`parquet`

對於所有基於表的連接器，請使用列舉值： tabular.

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: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Protocols source connection",
        "baseConnectionId": "a5c6b647-e784-4b58-86b6-47e784ab580b",
        "description": "Protocols source connection to ingest Orders",
        "data": {
            "format": "tabular",
        },
        "params": {
            "path": "Orders"
        },
        "connectionSpec": {
            "id": "8e6b41a8-d998-4545-ad7d-c6a9fff406c3",
            "version": "1.0"
        }
    }'

屬性	說明
`baseConnectionId`	您的通訊協定應用程式的連線ID
`params.path`	源檔案的路徑。
`connectionSpec.id`	您的協定應用程式的連接規範ID。

回應

成功的響應返回新建立的源連id接的唯一標識符()。在後續步驟中需要此ID才能建立目標連線。

{
    "id": "0a768941-ddfb-499d-b689-41ddfbf99db0",
    "etag": "\"8f00753e-0000-0200-0000-5e8a547d0000\""
}

建立目標XDM模式

在之前的步驟中，會建立臨機XDM架構來結構來源資料。為了使用源資料，還必須創 Platform建目標模式，以根據您的需要構建源資料。然後，目標模式用於建立包含 Platform 源資料的資料集。此目標XDM模式還擴展了XDM Individual Profile 類。

通過對方案註冊表API執行POST請求，可以建立目標XDM 方案。如果希望在中使用用戶介面 Experience Platform, Schema Editor教程將提供在Schema Editor中執行類似操作的逐步說明。
API格式

POST /tenant/schemas

請求

以下示例請求建立了擴展XDM類的XDM Individual Profile 架構。

curl -X POST \
    'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "type": "object",
        "title": "Target schema for protocols",
        "description": "Target schema for protocols",
        "allOf": [
            {
                "$ref": "https://ns.adobe.com/xdm/context/profile"
            },
            {
                "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
            },
            {
                "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
            },
                    {
                "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
            }
        ],
        "meta:containerId": "tenant",
        "meta:resourceType": "schemas",
        "meta:xdmType": "object",
        "meta:class": "https://ns.adobe.com/xdm/context/profile"
}'

回應

成功的回應會傳回新建立之架構的詳細資料，包括其唯一識別碼($id)。在後續步驟中需要此ID，才能建立目標資料集、對應和資料流。

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/e669d7aba5a02f294fafb7b269af25f7cd4a66ce59193545",
    "meta:altId": "_{TENANT_ID}.schemas.e669d7aba5a02f294fafb7b269af25f7cd4a66ce59193545",
    "meta:resourceType": "schemas",
    "version": "1.0",
    "title": "Protocols target schema",
    "type": "object",
    "description": "Protocols target schema",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details",
            "type": "object",
            "meta:xdmType": "object"
        }
    ],
    "refs": [
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/xdm/context/profile"
    ],
    "imsOrg": "7DC732555AECDB4C0A494036@AdobeOrg",
    "meta:extensible": false,
    "meta:abstract": false,
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/profile"
    ],
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createdDate": 1586124086523,
        "repo:lastModifiedDate": 1586124086523,
        "xdm:createdClientId": "{CREATED_CLIENT_ID}",
        "xdm:lastModifiedClientId": "{LAST_MODIFIED_CLIENT_ID}",
        "xdm:createdUserId": "{CREATED_USER_ID}",
        "xdm:lastModifiedUserId": "{LAST_MODIFIED_USER_ID}",
        "eTag": "8b281c23af03ff6a8b7d8061c62d73f7bcbfa1fc7dbabebfb4d8ca77130576ca"
    },
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:containerId": "tenant",
    "meta:tenantNamespace": "_{TENANT_ID}"
}

建立目標資料集

目標資料集可以通過對目錄服務 API執行POST請求，提供裝載內目標方案的ID來建立。

API格式

POST /dataSets

請求

curl -X POST \
    'https://platform.adobe.io/data/foundation/catalog/dataSets?requestDataSource=true' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Protocols target dataset",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/e669d7aba5a02f294fafb7b269af25f7cd4a66ce59193545",
            "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
        }
    }'

屬性	說明
`schemaRef.id`	目 `$id` 標XDM模式的。

回應

成功的回應會傳回包含新建立資料集ID的陣列，格式為 "@/datasets/{DATASET_ID}"。資料集ID是唯讀、系統產生的字串，用於在API呼叫中參考資料集。在後續步驟中，依需要儲存目標資料集ID以建立目標連線和資料流。

[
    "@/dataSets/5e8a55ca53662c18af37a83a"
]

建立目標連接

目標連接表示到所收錄資料所在目的地的連接。要建立目標連接，必須提供與資料庫關聯的固定連接規範ID。此連接規範ID為： c604ff05-7f1a-43c0-8e18-33bf874cb11c.

您現在擁有目標資料集的唯一識別碼、目標模式，以及與資料湖的連線規範ID。使用這些識別碼，您可以使用 Flow Service API建立目標連線，以指定將包含傳入來源資料的資料集。

API格式

POST /targetConnections

請求

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Target Connection for protocols",
        "description": "Target Connection for protocols",
        "data": {
            "format": "parquet_xdm",
            "schema": {
                "id": "https://ns.adobe.com/{TENANT_ID}/schemas/e669d7aba5a02f294fafb7b269af25f7cd4a66ce59193545",
            }
        },
        "params": {
            "dataSetId": "5e8a55ca53662c18af37a83a"
        },
            "connectionSpec": {
            "id": "8e6b41a8-d998-4545-ad7d-c6a9fff406c3",
            "version": "1.0"
        }
    }'

屬性	說明
`data.schema.id`	目 `$id` 標XDM模式的。
`params.dataSetId`	目標資料集的ID。
`connectionSpec.id`	已修正連接規範ID到資料湖。此ID為： `c604ff05-7f1a-43c0-8e18-33bf874cb11c`.

回應

成功的回應會傳回新目標連線的唯一識別碼(id)。在後續步驟中需要此值才能建立資料流。

{
    "id": "576d5ecf-f114-4587-ad5e-cff1144587f4",
    "etag": "\"13013506-0000-0200-0000-5e8a56d80000\""
}

建立對應

為了將源資料引入目標資料集，必須首先將其映射到目標資料集所遵守的目標模式。這是透過對轉換服務API執行POST要求，並在請求裝載中定義資料映射，來實現的。

API格式

POST /mappingSets

請求

curl -X POST \
    'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "version": 0,
        "xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/e669d7aba5a02f294fafb7b269af25f7cd4a66ce59193545",
        "xdmVersion": "1.0",
        "id": null,
        "mappings": [
            {
                "destinationXdmPath": "_id",
                "sourceAttribute": "OrderID",
                "identity": false,
                "identityGroup": null,
                "namespaceCode": null,
                "version": 0
            },
            {
                "destinationXdmPath": "_id",
                "sourceAttribute": "CustomerID",
                "identity": false,
                "identityGroup": null,
                "namespaceCode": null,
                "version": 0
            },
            {
                "destinationXdmPath": "_id",
                "sourceAttribute": "EmployeeID",
                "identity": false,
                "identityGroup": null,
                "namespaceCode": null,
                "version": 0
            },
            {
                "destinationXdmPath": "createdByBatchID",
                "sourceAttribute": "OrderDate",
                "identity": false,
                "identityGroup": null,
                "namespaceCode": null,
                "version": 0
            }
        ]
    }'

屬性	說明
`xdmSchema`	目 `$id` 標XDM模式的。

回應

成功的回應會傳回新建立之對應的詳細資訊，包括其唯一識別碼(id)。在後續步驟中需要此ID才能建立資料流。

{
    "id": "37409d3017e24a3eb4a2dc21020f7a5b",
    "version": 0,
    "createdDate": 1586124873209,
    "modifiedDate": 1586124873209,
    "createdBy": "28AF22BA5DE6B0B40A494036@AdobeID",
    "modifiedBy": "28AF22BA5DE6B0B40A494036@AdobeID"
}

查找資料流規範

資料流負責從源收集資料並將其引入 Platform。要建立資料流，必須首先通過對 Flow Service API執行GET請求來獲取資料流規範。資料流規範負責從外部協定應用程式收集資料。

API格式

GET /flowSpecs?property=name=="CRMToAEP"

請求

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name=="CRMToAEP"' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'

回應

成功的響應返回負責將協定應用程式中的資料引入資料流規範的詳細資訊 Platform。在下一步中需要此ID才能建立新的資料流。

{
    "items": [
        {
            "id": "14518937-270c-4525-bdec-c2ba7cce3860",
            "name": "CRMToAEP",
            "providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
            "version": "1.0",
            "transformationSpecs": [
                {
                    "name": "Copy",
                    "spec": {
                        "$schema": "http://json-schema.org/draft-07/schema#",
                        "type": "object",
                        "properties": {
                            "deltaColumn": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "dateFormat": {
                                        "type": "string"
                                    },
                                    "timezone": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        },
                        "required": [
                            "deltaColumn"
                        ]
                    }
                },
                {
                    "name": "Mapping",
                    "spec": {
                        "$schema": "http://json-schema.org/draft-07/schema#",
                        "type": "object",
                        "description": "defines various params required for different mapping from source to target",
                        "properties": {
                            "mappingId": {
                                "type": "string"
                            },
                            "mappingVersion": {
                                "type": "string"
                            }
                        }
                    }
                }
            ],
            "scheduleSpec": {
                "name": "PeriodicSchedule",
                "type": "Periodic",
                "spec": {
                    "$schema": "http://json-schema.org/draft-07/schema#",
                    "type": "object",
                    "properties": {
                        "startTime": {
                            "description": "epoch time",
                            "type": "integer"
                        },
                        "endTime": {
                            "description": "epoch time",
                            "type": "integer"
                        },
                        "interval": {
                            "type": "integer"
                        },
                        "frequency": {
                            "type": "string",
                            "enum": [
                                "minute",
                                "hour",
                                "day",
                                "week"
                            ]
                        },
                        "backfill": {
                            "type": "boolean",
                            "default": true
                        }
                    },
                    "required": [
                        "startTime",
                        "frequency",
                        "interval"
                    ],
                    "if": {
                        "properties": {
                            "frequency": {
                                "const": "minute"
                            }
                        }
                    },
                    "then": {
                        "properties": {
                            "interval": {
                                "minimum": 15
                            }
                        }
                    },
                    "else": {
                        "properties": {
                            "interval": {
                                "minimum": 1
                            }
                        }
                    }
                }
            }
        }
    ]
}

建立資料流

收集資料的最後一步是建立資料流。此時，您應準備下列必要值：

源連接ID
目標連線ID
對應ID
資料流規範ID

資料流負責調度和收集源中的資料。您可以通過執行POST請求來建立資料流，同時在裝載中提供先前提到的值。

若要排程擷取，您必須先將開始時間值設定為以秒為單位的紀元時間。然後，您必須將頻率值設為以下五個選項之一： once、 minute、 hour、 day或 week。間隔值指定兩個連續的提取之間的期間，並且建立一次性提取不需要設定間隔。對於所有其它頻率，間隔值必須設定為等於或大於 15。

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: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Creating a dataflow for a protocols source",
        "description": "Creating a dataflow for a protocols source",
        "flowSpec": {
            "id": "14518937-270c-4525-bdec-c2ba7cce3860",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "0a768941-ddfb-499d-b689-41ddfbf99db0"
        ],
        "targetConnectionIds": [
            "576d5ecf-f114-4587-ad5e-cff1144587f4"
        ],
        "transformations": [
            {
                "name": "Copy",
                "params": {
                    "deltaColumn": {
                        "name": "updatedAt",
                        "dateFormat": "YYYY-MM-DD",
                        "timezone": "UTC"
                    }
                }
            },
            {
                "name": "Mapping",
                "params": {
                    "mappingId": "7409d3017e24a3eb4a2dc21020f7a5b",
                    "mappingVersion": "0"
                }
            }
        ],
        "scheduleParams": {
            "startTime": "1567411548",
            "frequency":"minute",
            "interval":"30"
        }
    }'

屬性	說明
`flowSpec.id`	在上一步驟中檢索的流式規範ID 。
`sourceConnectionIds`	在先前步驟中擷取的來源連線ID 。
`targetConnectionIds`	在先前步驟中擷取的目標連線ID 。
`transformations.params.mappingId`	在先前步驟中擷取的對應ID。
`transformations.params.deltaColum`	用於區分新資料和現有資料的指定欄。增量資料將根據選取欄的時間戳記進行擷取。使用Generic OData時支 `deltaColumn` 持的格式為 `yyyy-MM-ddTHH:mm:ssZ`。
`transformations.params.mappingId`	與資料庫關聯的映射ID。
`scheduleParams.startTime`	資料流在時代時間中的開始時間。
`scheduleParams.frequency`	資料流收集資料的頻率。可接受的值包括： `once`、 `minute`、 `hour`、 `day`或 `week`。
`scheduleParams.interval`	該間隔用於指定兩個連續流運行之間的期間。間隔的值應為非零整數。當頻率設為且應大於或等於其 `once` 他頻率值時，不需要 `15` 間隔。

回應

成功的響應返回新創 id 建的資料流的ID。

{
    "id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
    "etag": "\"04004fe9-0000-0200-0000-5ebc4c8b0000\""
}

監控資料流

建立資料流後，您可以監視通過其接收的資料，以查看有關流運行、完成狀態和錯誤的資訊。有關如何監視資料流的詳細資訊，請參見API中有關監視資料流的教程

後續步驟

在本教學課程中，您已建立來源連接器，以依排程從通訊協定應用程式收集資料。現在，下游服務（例如和）可 Platform 以使用傳入 Real-time Customer Profile 的資料 Data Science Workspace。如需詳細資訊，請參閱下列檔案：

adobe.com 上的資源

Personalized Communications Customer Analytics Mobile Analytics Target Market Segmentation Data Ingestion Advertising

透過來源連接器和API收集通訊協定資料

快速入門

讀取範例API呼叫

收集必要標題的值

建立源連接

建立目標XDM模式

建立目標資料集

建立目標連接

建立對應

查找資料流規範

建立資料流

監控資料流

後續步驟

adobe.com 上的資源

本頁內容

檢視下一個: