文件Experience Platform來源連接器指南

使用Flow Service API連線Microsoft Dynamics至Experience Platform

Last update: Fri Apr 04 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主題：

建立對象：

  • 開發人員

閱讀本指南，瞭解如何使用Flow Service API將您的Microsoft Dynamics來源連結至Adobe Experience Platform。

快速入門

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

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

使用Experience Platform API

如需如何成功呼叫Experience Platform API的詳細資訊，請參閱Experience Platform API快速入門指南。

下列章節提供您需瞭解的其他資訊，才能使用Flow Service API成功將Experience Platform連線至Dynamics帳戶。

收集必要的認證

為了讓Flow Service連線到Dynamics，您必須提供下列連線屬性的值：

基本驗證
table 0-row-2 1-row-2 2-row-2 3-row-2
認證 說明
serviceUri Dynamics執行個體的服務URL。
username 您的Dynamics使用者帳戶的使用者名稱。
password 您的Dynamics帳戶密碼。
服務主體和金鑰驗證
table 0-row-2 1-row-2 2-row-2
認證 說明
servicePrincipalId 您Dynamics帳戶的使用者端識別碼。 使用服務主體和金鑰式驗證時，需要此ID。
servicePrincipalKey 服務主體秘密金鑰。 使用服務主體和金鑰式驗證時，需要此認證。

如需開始使用的詳細資訊，請參閱此 Dynamics 檔案。

建立基礎連線

TIP
建立後，您無法變更Dynamics基本連線的驗證型別。 若要變更驗證型別，您必須建立新的基礎連線。

基本連線會保留來源與Experience Platform之間的資訊，包括來源的驗證認證、連線的目前狀態，以及唯一的基本連線ID。 基礎連線ID可讓您從來源內部探索及導覽檔案，並識別您要擷取的特定專案，包括其資料型別和格式的資訊。

若要建立基底連線ID，請在提供您的Dynamics驗證認證作為要求引數的一部分時，對/connections端點提出POST要求。

API格式

POST /connections
基本驗證

若要使用基本驗證建立Dynamics基本連線，請在提供連線的serviceUri、username和password的值時，對Flow Service API提出POST要求。

要求

下列要求使用基本驗證建立Dynamics來源的基本連線。

accordion
選取以檢視請求範例
code language-shell 
curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/connections' \
  -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": "Dynamics connection",
      "description": "Dynamics connection using basic auth",
      "auth": {
          "specName": "Basic Authentication for Dynamics-Online",
          "params": {
              "serviceUri": "{SERVICE_URI}",
              "username": "{USERNAME}",
              "password": "{PASSWORD}"
          }
      },
      "connectionSpec": {
          "id": "38ad80fe-8b06-4938-94f4-d4ee80266b07",
          "version": "1.0"
      }
  }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
屬性 說明
auth.params.serviceUri 與您的Dynamics執行個體關聯的服務URI。
auth.params.username 與您的Dynamics帳戶相關聯的使用者名稱。
auth.params.password 與您的Dynamics帳戶關聯的密碼。
connectionSpec.id Dynamics連線規格識別碼： 38ad80fe-8b06-4938-94f4-d4ee80266b07

回應

成功的回應會傳回新建立的基礎連線，包括其唯一識別碼(id)。

accordion
選取以檢視回應範例
code language-json 
{
    "id": "4cb0c374-d3bb-4557-b139-5712880adc55",
    "etag": "\"9e0052a2-0000-0200-0000-5e35tb330000\""
}
服務主要金鑰式驗證

若要使用服務主體金鑰式驗證來建立Dynamics基底連線，請對Flow Service API提出POST要求，同時為您連線的serviceUri、servicePrincipalId和servicePrincipalKey提供值。

要求

下列要求會使用基本服務主要金鑰式驗證，為Dynamics來源建立基礎連線。

accordion
選取以檢視請求範例
code language-shell 
curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/connections' \
  -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": "Dynamics connection",
      "description": "Dynamics connection using key-based authentication",
      "auth": {
          "specName": "Service Principal Key Based Authentication",
          "params": {
              "serviceUri": "{SERVICE_URI}",
              "servicePrincipalId": "{SERVICE_PRINCIPAL_ID}",
              "servicePrincipalKey": "{SERVICE_PRINCIPAL_KEY}"
          }
      },
      "connectionSpec": {
          "id": "38ad80fe-8b06-4938-94f4-d4ee80266b07",
          "version": "1.0"
      }
  }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
屬性 說明
auth.params.serviceUri 與您的Dynamics執行個體關聯的服務URI。
auth.params.servicePrincipalId 您Dynamics帳戶的使用者端識別碼。 使用服務主體和金鑰式驗證時，需要此ID。
auth.params.servicePrincipalKey 服務主體秘密金鑰。 使用服務主體和金鑰式驗證時，需要此認證。
connectionSpec.id Dynamics連線規格識別碼： 38ad80fe-8b06-4938-94f4-d4ee80266b07

回應

成功的回應會傳回新建立的連線，包括其唯一識別碼(id)。

accordion
選取以檢視回應範例
code language-json 
{
    "id": "4cb0c374-d3bb-4557-b139-5712880adc55",
    "etag": "\"9e0052a2-0000-0200-0000-5e35tb330000\""
}

探索您的資料表

若要探索您的Dynamics資料表，請向/connections/{BASE_CONNECTION_ID}/explore端點發出GET請求，並提供您的基本連線ID作為查詢引數的一部分。

API格式

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=root
查詢參數
說明
{BASE_CONNECTION_ID}
基礎連線的ID。 使用此ID來探索來源的內容和結構。

要求

下列要求會擷取基底連線識別碼為dd668808-25da-493f-8782-f3433b976d1e之Dynamics來源的可用資料表和檢視清單。

選取以檢視請求範例
code language-shell 
curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/connections/dd668808-25da-493f-8782-f3433b976d1e/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}' \
  -H 'Content-Type: application/json' \

回應

成功的回應傳回根層級的Dynamics資料表和檢視目錄。

選取以檢視回應範例
code language-json 
[
    {
        "type": "table",
        "name": "systemuserlicenses",
        "path": "systemuserlicenses",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "table",
        "name": "Process Dependency",
        "path": "workflowdependency",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "view",
        "name": "accountView1",
        "path": "accountView1",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "view",
        "name": "Inactive_ACC_custom",
        "path": "Inactive_ACC_custom",
        "canPreview": true,
        "canFetchSchema": true
    }
]

使用主索引鍵來最佳化資料探索

NOTE
使用主要索引鍵進行最佳化時，您只能使用非查詢屬性。

您可以將primaryKey作為查詢引數的一部分提供，以最佳化您的探索查詢。 包含primaryKey作為查詢引數時，您必須指定Dynamics資料表的主索引鍵。

API格式

GET /connections/{BASE_CONNECTION_ID}/explore?preview=true&object={OBJECT}&objectType={OBJECT_TYPE}&previewCount=10&primaryKey={PRIMARY_KEY}
查詢參數
說明
{BASE_CONNECTION_ID}
基礎連線的ID。 使用此ID來探索來源的內容和結構。
preview
啟用資料預覽的布林值。
{OBJECT}
您要探索的Dynamics物件。
{OBJECT_TYPE}
物件的型別。
previewCount
限制傳回的預覽僅能預覽特定數量的記錄。
{PRIMARY_KEY}
您要擷取以供預覽之表格的主索引鍵。

要求

選取以檢視請求範例
code language-shell 
curl -X GET \
  'https://platform-stage.adobe.io/data/foundation/flowservice/connections/dd668808-25da-493f-8782-f3433b976d1e/explore?preview=true&object=lead&objectType=table&previewCount=10&primaryKey=leadid' \
  -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' \

檢查表格的結構

若要檢查特定表格的結構，請向/connections/{BASE_CONNECTION_ID}/explore發出GET請求，並提供特定表格的路徑作為查詢引數。

API格式

GET /connections/{BASE_CONNECTION_ID}/explore?object={TABLE_PATH}&objectType=table
查詢引數
說明
{BASE_CONNECTION_ID}
基礎連線的ID。 使用此ID來探索來源的內容和結構。
{TABLE_PATH}
您要探索的特定表格的路徑。

要求

下列要求會擷取路徑為workflowdependency之Dynamics表格的結構和內容。

選取以檢視請求範例
code language-shell 
curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/connections/dd668808-25da-493f-8782-f3433b976d1e/explore?object=workflowdependency&objectType=table' \
  -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' \

回應

成功的回應傳迴路徑workflowdependency的內容。

選取以檢視回應範例
code language-json 
{
    "format": "flat",
    "schema": {
        "columns": [
            {
                "name": "first_name",
                "type": "string",
                "meta": {
                    "originalType": "String"
                }
            },
            {
                "name": "last_name",
                "type": "string",
                "meta": {
                    "originalType": "String"
                }
            },
            {
                "name": "email",
                "type": "string",
                "meta": {
                    "originalType": "String"
                }
            }
        ]
    }
}

檢查檢視的結構

在Dynamics中，檢視是指要顯示的欄、每欄的寬度、記錄清單排序的預設系統，以及套用的預設篩選器，以限制清單中出現的記錄。

若要檢查檢視的結構，請向/connections/{BASE_CONNECTION_ID}/explore發出GET要求，並在您的查詢引數中指定檢視路徑。 此外，您必須指定objectType為view。

API格式

GET /connections/{BASE_CONNECTION_ID}/explore?object={VIEW_PATH}&objectType=view
查詢引數
說明
{BASE_CONNECTION_ID}
基礎連線的ID。 使用此ID來探索來源的內容和結構。
{VIEW_PATH}
您要檢查的檢視的路徑。

要求

下列要求會擷取accountView1。

選取以檢視請求範例
code language-shell 
curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/connections/dd668808-25da-493f-8782-f3433b976d1e/explore?object=accountView1&objectType=view' \
  -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' \

回應

成功的回應傳回accountView1的結構。

選取以檢視回應範例
code language-json 
{
    "format": "flat",
    "schema": {
        "columns": [
            {
                "name": "name",
                "type": "string",
                "meta": {
                    "originalType": "string"
                },
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "fetchxml",
                "type": "string",
                "meta": {
                    "originalType": "string"
                },
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "querytype",
                "type": "integer",
                "meta": {
                    "originalType": "int"
                },
                "xdm": {
                    "type": "integer",
                    "minimum": -2147483648,
                    "maximum": 2147483647
                }
            },
            {
                "name": "userqueryid",
                "type": "string",
                "meta": {
                    "originalType": "guid"
                },
                "xdm": {
                    "type": "string"
                }
            }
        ]
    }
}

預覽實體型別檢視

若要預覽檢視的內容，請向/connections/{BASE_CONNECTION_ID}/explore發出GET請求，並在您的查詢引數中包含檢視路徑以及preview=true。

API格式

GET /connections/{BASE_CONNECTION_ID}/explore?object={VIEW_PATH}&preview=true&objectType=view
查詢引數
說明
{BASE_CONNECTION_ID}
基礎連線的ID。 使用此ID來探索來源的內容和結構。
{VIEW_PATH}
您要檢查的檢視的路徑。

要求

下列要求會預覽accountView1的內容。

選取以檢視請求範例
code language-shell 
curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/connections/dd668808-25da-493f-8782-f3433b976d1e/explore?object=accountView1&preview=true&objectType=view' \
  -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' \

回應

成功的回應傳回accountView1的內容。

選取以檢視回應範例
code language-json 
{
    "format": "flat",
    "schema": {
        "columns": [
            {
                "name": "emailaddress1",
                "type": "string",
                "meta": {
                    "originalType": "string"
                },
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "contactid",
                "type": "string",
                "meta": {
                    "originalType": "guid"
                },
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "fullname",
                "type": "string",
                "meta": {
                    "originalType": "string"
                },
                "xdm": {
                    "type": "string"
                }
            }
        ]
    },
    "data": [
        {
            "contactid": "396e19de-0852-ec11-8c62-00224808a1df",
            "fullname": "Tim Barr",
            "emailaddress1": "barrtim@googlemedia.com"
        }
    ]
}

建立來源連線以擷取檢視

若要建立來源連線並擷取檢視，請對/sourceConnections端點提出POST要求、提供資料表名稱，並在要求內文中將entityType指定為view。

API格式

POST /sourceConnections

要求

下列要求會建立Dynamics來源連線並擷取檢視。

選取以檢視請求範例
code language-shell 
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": "Dynamics Source Connection",
      "description": "Dynamics Source Connection",
      "baseConnectionId": "dd668808-25da-493f-8782-f3433b976d1e",
      "data": {
          "format": "tabular",
          "schema": null,
          "properties": null
      },
      "params": {
          "tableName": "Contacts with name TIM",
          "entityType": "view"
      },
      "connectionSpec": {
          "id": "38ad80fe-8b06-4938-94f4-d4ee80266b07",
          "version": "1.0"
      }
  }'

回應

成功的回應會傳回新產生的來源連線ID及其對應的電子標籤。

選取以檢視回應範例
code language-json 
{
    "id": "e566bab3-1b58-428c-b751-86b8cc79a3b4",
    "etag": "\"82009592-0000-0200-0000-678121030000\""
}

使用主索引鍵來最佳化您的資料流

您也可以將主索引鍵指定為要求內文引數的一部分，以最佳化Dynamics資料流。

API格式

POST /sourceConnections

要求

將主索引鍵指定為contactid時，下列要求會建立Dynamics來源連線。

選取以檢視請求範例
code language-shell 
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": "Dynamics Source Connection",
      "description": "Dynamics Source Connection",
      "baseConnectionId": "dd668808-25da-493f-8782-f3433b976d1e",
      "data": {
          "format": "tabular"
      },
      "params": {
          "tableName": "contact",
          "primaryKey": "contactid"
      },
      "connectionSpec": {
          "id": "38ad80fe-8b06-4938-94f4-d4ee80266b07",
          "version": "1.0"
      }
  }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
屬性 說明
baseConnectionId 基礎連線的ID。
data.format 資料的格式。
params.tableName Dynamics中資料表的名稱。
params.primaryKey 將最佳化查詢之表格的主索引鍵。
connectionSpec.id 與Dynamics來源對應的連線規格識別碼。

回應

成功的回應會傳回新產生的來源連線ID及其對應的電子標籤。

選取以檢視回應範例
code language-json 
{
    "id": "e566bab3-1b58-428c-b751-86b8cc79a3b4",
    "etag": "\"82009592-0000-0200-0000-678121030000\""
}

後續步驟

依照此教學課程，您已使用Flow Service API建立Microsoft Dynamics基礎連線。 您可以在下列教學課程中使用此基本連線ID：

recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089