[Beta]{class="badge informative"}

為以下專案建立串流來源連線和資料流： Shopify 使用流量服務API的資料

Last update: Tue Oct 31 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：
Sources

建立對象：

Developer

NOTE

此 Shopify 串流來源為測試版。請閱讀來源概觀以取得有關使用測試版標籤來源的詳細資訊。

下列教學課程提供如何建立串流來源連線和資料流，以從中串流資料的步驟 Shopify 前往Adobe Experience Platform，使用 Flow Service API.

快速入門 getting-started

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

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

使用平台API

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

串流 Shopify 使用流量服務API將資料傳遞至Platform

以下概述建立來源連線和資料流以串流處理您的專案所需的步驟。 Shopify 資料到Platform。

建立來源連線 source-connection

透過向發出POST請求來建立來源連線 Flow Service api，同時提供來源的連線規格ID、名稱和說明等詳細資訊，以及資料的格式。

API格式

POST /sourceConnections

要求

以下請求會為建立來源連線 YOURSOURCE：

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": "Shopify Streaming Source Connection",
      "providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
      "description": "Shopify Streaming Source Connection",
      "connectionSpec": {
          "id": "e77fd9d2-22a8-11ed-861d-0242ac120002",
          "version": "1.0"
      },
      "data": {
          "format": "json"
      }
    }'

屬性

說明

name

來源連線的名稱。確定來源連線的名稱是描述性的，因為您可以使用此名稱來查詢來源連線的資訊。

description

您可以納入的選用值，可提供來源連線的詳細資訊。

connectionSpec.id

與您的來源對應的連線規格ID。

data.format

的格式 Shopify 您要擷取的資料。目前唯一支援的資料格式為 json.

回應

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

{
     "id": "246d052c-da4a-494a-937f-a0d17b1c6cf5",
     "etag": "\"712a8c08-fda7-41c2-984b-187f823293d8\""
}

建立目標XDM結構描述 target-schema

為了在Platform中使用來源資料，必須建立目標結構描述，以根據您的需求來建構來源資料。然後目標結構描述會用來建立包含來源資料的Platform資料集。

您可以透過對以下對象執行POST請求來建立目標XDM結構描述：結構描述登入API.

如需如何建立目標XDM結構的詳細步驟，請參閱以下教學課程：使用API建立結構描述.

建立目標資料集 target-dataset

您可以透過對執行POST請求來建立目標資料集目錄服務API，在裝載中提供目標結構描述的ID。

如需如何建立目標資料集的詳細步驟，請參閱教學課程，位於使用API建立資料集.

建立目標連線 target-connection

目標連線代表與要儲存所擷取資料的目的地之間的連線。若要建立目標連線，您必須提供對應至資料湖的固定連線規格ID。此ID為： c604ff05-7f1a-43c0-8e18-33bf874cb11c.

您現在擁有唯一識別碼、目標結構描述、目標資料集，以及與Data Lake的連線規格ID。使用這些識別碼，您可以使用以下專案建立目標連線： Flow Service API可指定將包含傳入來源資料的資料集。

API格式

POST /targetConnections

要求

以下請求會為建立目標連線 Shopify：

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "Shopify Streaming Target Connection",
      "description": "Shopify Streaming Target Connection",
      "connectionSpec": {
          "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
          "version": "1.0"
      },
      "data": {
          "format": "json",
          "schema": {
              "id": "{TARGET_XDM_SCHEMA}",
              "version": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
      "params": {
          "dataSetId": "{TARGET_DATASET}"
      }
  }'

屬性

說明

name

目標連線的名稱。請確定目標連線的名稱是描述性的，因為您可以使用此名稱來查詢目標連線的資訊。

description

您可以納入的選用值，可提供目標連線的詳細資訊。

connectionSpec.id

對應至資料湖的連線規格ID。此固定ID為： c604ff05-7f1a-43c0-8e18-33bf874cb11c.

data.format

的格式 Shopify 您要帶到Platform的資料。

params.dataSetId

在上一步中擷取的目標資料集ID。

回應

成功回應會傳回新目標連線的唯一識別碼(id)。此ID在後續步驟中是必要的。

{
     "id": "7c96c827-3ffd-460c-a573-e9558f72f263",
     "etag": "\"a196f685-f5e8-4c4c-bfbd-136141bb0c6d\""
}

建立對應 mapping

為了將來源資料擷取到目標資料集中，必須首先將其對應到目標資料集所堅持的目標結構描述。這是透過向執行POST請求來達成 Data Prep API 要求裝載中定義資料對應。

API格式

POST /conversion/mappingSets

要求

curl -X POST \
  'https://platform.adobe.io/data/foundation/mappingSets' \
  -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 '{
      "version": 0,
      "xdmSchema": "{TARGET_XDM_SCHEMA}",
      "xdmVersion": "1.0",
      "mappings": [
          {
              "destinationXdmPath": "person.name.firstName",
              "sourceAttribute": "firstName",
              "identity": false,
              "version": 0
          },
          {
              "destinationXdmPath": "person.name.lastName",
              "sourceAttribute": "lastName",
              "identity": false,
              "version": 0
          }
      ]
  }'

屬性

說明

xdmSchema

的ID 目標XDM結構描述已在先前步驟中產生。

mappings.destinationXdmPath

來源屬性對應到的目的地XDM路徑。

mappings.sourceAttribute

需要對映至目的地XDM路徑的來源屬性。

mappings.identity

布林值，指定是否要將對應集標示為 Identity Service.

回應

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

{
    "id": "bf5286a9c1ad4266baca76ba3adc9366",
    "version": 0,
    "createdDate": 1597784069368,
    "modifiedDate": 1597784069368,
    "createdBy": "{CREATED_BY}",
    "modifiedBy": "{MODIFIED_BY}"
}

建立流程 flow

從匯入資料的最後一步 Shopify 到Platform就是建立資料流。到現在為止，您已準備下列必要值：

來源連線ID
目標連線ID
對應 ID

資料流負責從來源排程及收集資料。您可以執行POST要求，同時在裝載中提供先前提到的值，藉此建立資料流。

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": "Shopify Streaming Dataflow",
      "description": "Shopify Streaming Dataflow",
      "flowSpec": {
          "id": "e77fde5a-22a8-11ed-861d-0242ac120002",
          "version": "1.0"
      },
      "sourceConnectionIds": [
          "246d052c-da4a-494a-937f-a0d17b1c6cf5"
      ],
      "targetConnectionIds": [
          "7c96c827-3ffd-460c-a573-e9558f72f263"
      ],
      "transformations": [
      {
        "name": "Mapping",
        "params": {
          "mappingId": "bf5286a9c1ad4266baca76ba3adc9366",
          "mappingVersion": 0
        }
      }
    ]
  }'

屬性

說明

name

資料流的名稱。確保資料流的名稱為描述性，因為您可以使用此名稱來查詢資料流上的資訊。

description

您可以納入的選用值，可提供資料流的詳細資訊。

flowSpec.id

建立資料流所需的流量規格ID。此固定ID為： e77fde5a-22a8-11ed-861d-0242ac120002.

flowSpec.version

流程規格ID的對應版本。此值預設為 1.0.

sourceConnectionIds

此來源連線ID 已在先前步驟中產生。

targetConnectionIds

此目標連線ID 已在先前步驟中產生。

transformations

此屬性包含套用至資料所需的各種轉換。將非XDM相容的資料引進Platform時，需要此屬性。

transformations.name

指定給轉換的名稱。

transformations.params.mappingId

此對應ID 已在先前步驟中產生。

transformations.params.mappingVersion

對應ID的對應版本。此值預設為 0.

回應

成功的回應會傳回ID (id)。您可以使用此ID來監視、更新或刪除資料流。

{
     "id": "993f908f-3342-4d9c-9f3c-5aa9a189ca1a",
     "etag": "\"510bb1d4-8453-4034-b991-ab942e11dd8a\""
}

取得您的串流端點URL

建立資料流後，您現在可以擷取串流端點URL。您將使用此端點URL來將您的來源訂閱給webhook，以允許您的來源與Experience Platform通訊。

GET若要擷取您的串流端點URL，請對 /flows 端點並提供資料流的ID。

API格式

GET /flows/{FLOW_ID}

要求

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/flows/993f908f-3342-4d9c-9f3c-5aa9a189ca1a' \
  -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}'

回應

成功的回應會傳回資料流上的資訊，包括標示為 inletUrl.

{
   "header":{
      "xactionId":"1658464615769:0062:161",
      "source":{
         "name":"shopify"
      },
      "sandboxId":"d537df80-c5d7-11e9-aafb-87c71c35cac8",
      "sandboxName":"prod",
      "originalTimestamp":1658464615770,
      "msgId":"1658464615769:0062:161",
      "msgVersion":"1.0",
      "traceContext":{
         "traceId":"ff3e7544618471eee6b934a4c5929d4e",
         "spanId":"74a759c5cc5f5a06",
         "isSampled":1.0
      },
      "_dcsMeta":{
         "inletId":"9d411a24aa3c0a3eded92bac6c64d0da986ee7a8212f87168c5fb42d9ddc3227",
         "authenticatedRequest":false,
         "debug":true
      }
   },
   "body":{
      "id":4135234371722,
      "admin_graphql_api_id":"gid://shopify/Order/4135234371722",
      "app_id":1354745,
      "browser_ip":null,
      "buyer_accepts_marketing":false,
      "cancel_reason":null,
      "cancelled_at":null,
      "cart_token":null,
      "checkout_id":21706716217482,
      "checkout_token":"b143503216124d50141fe0832fa3f4b0",
      "client_details":{
         "accept_language":null,
         "browser_height":null,
         "browser_ip":null,
         "browser_width":null,
         "session_hash":null,
         "user_agent":null
      },
      "closed_at":null,
      "confirmed":true,
      "contact_email":null,
      "created_at":"2022-07-22T00:36:48-04:00",
      "currency":"INR",
      "current_subtotal_price":"40000.00",
      "current_subtotal_price_set":{
         "shop_money":{
            "amount":"40000.00",
            "currency_code":"INR"
         },
         "presentment_money":{
            "amount":"40000.00",
            "currency_code":"INR"
         }
      },
      "current_total_discounts":"0.00",
      "current_total_discounts_set":{
         "shop_money":{
            "amount":"0.00",
            "currency_code":"INR"
         },
         "presentment_money":{
            "amount":"0.00",
            "currency_code":"INR"
         }
      },
      "current_total_duties_set":null,
      "current_total_price":"47200.00",
      "current_total_price_set":{
         "shop_money":{
            "amount":"47200.00",
            "currency_code":"INR"
         },
         "presentment_money":{
            "amount":"47200.00",
            "currency_code":"INR"
         }
      },
      "current_total_tax":"7200.00",
      "current_total_tax_set":{
         "shop_money":{
            "amount":"7200.00",
            "currency_code":"INR"
         },
         "presentment_money":{
            "amount":"7200.00",
            "currency_code":"INR"
         }
      },
      "customer_locale":null,
      "device_id":null,
      "discount_codes":[

      ],
      "email":"",
      "estimated_taxes":false,
      "financial_status":"paid",
      "fulfillment_status":null,
      "gateway":"manual",
      "landing_site":null,
      "landing_site_ref":null,
      "location_id":39129743498,
      "name":"#1005",
      "note":null,
      "note_attributes":[

      ],
      "number":5,
      "order_number":1005,
      "order_status_url":"https://connnectors-test.myshopify.com/31913214090/orders/ffd48198c78ef460177e44e22b19e6ab/authenticate?key=79a40d7da4b23d6a0beb2ba774f6ac83",
      "original_total_duties_set":null,
      "payment_gateway_names":[
         "manual"
      ],
      "phone":null,
      "presentment_currency":"INR",
      "processed_at":"2022-07-22T00:36:48-04:00",
      "processing_method":"manual",
      "reference":null,
      "referring_site":null,
      "source_identifier":null,
      "source_name":"shopify_draft_order",
      "source_url":null,
      "subtotal_price":"40000.00",
      "subtotal_price_set":{
         "shop_money":{
            "amount":"40000.00",
            "currency_code":"INR"
         },
         "presentment_money":{
            "amount":"40000.00",
            "currency_code":"INR"
         }
      },
      "tags":"",
      "tax_lines":[
         {
            "price":"7200.00",
            "rate":0.18,
            "title":"IGST",
            "price_set":{
               "shop_money":{
                  "amount":"7200.00",
                  "currency_code":"INR"
               },
               "presentment_money":{
                  "amount":"7200.00",
                  "currency_code":"INR"
               }
            },
            "channel_liable":false
         }
      ],
      "taxes_included":false,
      "test":false,
      "token":"ffd48198c78ef460177e44e22b19e6ab",
      "total_discounts":"0.00",
      "total_discounts_set":{
         "shop_money":{
            "amount":"0.00",
            "currency_code":"INR"
         },
         "presentment_money":{
            "amount":"0.00",
            "currency_code":"INR"
         }
      },
      "total_line_items_price":"40000.00",
      "total_line_items_price_set":{
         "shop_money":{
            "amount":"40000.00",
            "currency_code":"INR"
         },
         "presentment_money":{
            "amount":"40000.00",
            "currency_code":"INR"
         }
      },
      "total_outstanding":"0.00",
      "total_price":"47200.00",
      "total_price_set":{
         "shop_money":{
            "amount":"47200.00",
            "currency_code":"INR"
         },
         "presentment_money":{
            "amount":"47200.00",
            "currency_code":"INR"
         }
      },
      "total_price_usd":"589.95",
      "total_shipping_price_set":{
         "shop_money":{
            "amount":"0.00",
            "currency_code":"INR"
         },
         "presentment_money":{
            "amount":"0.00",
            "currency_code":"INR"
         }
      },
      "total_tax":"7200.00",
      "total_tax_set":{
         "shop_money":{
            "amount":"7200.00",
            "currency_code":"INR"
         },
         "presentment_money":{
            "amount":"7200.00",
            "currency_code":"INR"
         }
      },
      "total_tip_received":"0.00",
      "total_weight":800,
      "updated_at":"2022-07-22T00:36:49-04:00",
      "user_id":44968935562,
      "discount_applications":[

      ],
      "fulfillments":[

      ],
      "line_items":[
         {
            "id":10630730743946,
            "admin_graphql_api_id":"gid://shopify/LineItem/10630730743946",
            "fulfillable_quantity":1,
            "fulfillment_service":"manual",
            "fulfillment_status":null,
            "gift_card":false,
            "grams":800,
            "name":"Mobile Phones",
            "origin_location":{
               "id":3141069111434,
               "country_code":"IN",
               "province_code":"UP",
               "name":"Noida",
               "address1":"Noida",
               "address2":"",
               "city":"Noida",
               "zip":"201301"
            },
            "price":"40000.00",
            "price_set":{
               "shop_money":{
                  "amount":"40000.00",
                  "currency_code":"INR"
               },
               "presentment_money":{
                  "amount":"40000.00",
                  "currency_code":"INR"
               }
            },
            "product_exists":true,
            "product_id":4525859963018,
            "properties":[

            ],
            "quantity":1,
            "requires_shipping":true,
            "sku":"",
            "taxable":true,
            "title":"Mobile Phones",
            "total_discount":"0.00",
            "total_discount_set":{
               "shop_money":{
                  "amount":"0.00",
                  "currency_code":"INR"
               },
               "presentment_money":{
                  "amount":"0.00",
                  "currency_code":"INR"
               }
            },
            "variant_id":32045196640394,
            "variant_inventory_management":"shopify",
            "variant_title":"",
            "vendor":"Connnectors Test",
            "tax_lines":[
               {
                  "channel_liable":false,
                  "price":"7200.00",
                  "price_set":{
                     "shop_money":{
                        "amount":"7200.00",
                        "currency_code":"INR"
                     },
                     "presentment_money":{
                        "amount":"7200.00",
                        "currency_code":"INR"
                     }
                  },
                  "rate":0.18,
                  "title":"IGST"
               }
            ],
            "duties":[

            ],
            "discount_allocations":[

            ]
         }
      ],
      "payment_terms":null,
      "refunds":[

      ],
      "shipping_lines":[

      ]
   }
}

附錄

下節提供監視、更新和刪除資料流時可採取之步驟的相關資訊。

監視資料流

建立資料流後，您可以監視透過該資料流擷取的資料，以檢視有關資料流執行、完成狀態和錯誤的資訊。如需完整的API範例，請閱讀以下指南：使用API監控您的來源資料流.

更新您的資料流

透過向以下專案發出PATCH請求，更新資料流的詳細資訊，例如其名稱和說明，以及其執行排程和相關聯的對應集 /flows 的端點 Flow Service API，同時提供資料流的ID。提出PATCH請求時，您必須提供資料流的 etag 在 If-Match 標頭。如需完整的API範例，請閱讀以下指南：使用API更新來源資料流

更新您的帳戶

透過對執行PATCH請求，更新來源帳戶的名稱、說明和認證 Flow Service API，同時提供您的基本連線ID作為查詢引數。提出PATCH請求時，您必須提供來源帳戶的唯一值 etag 在 If-Match 標頭。如需完整的API範例，請閱讀以下指南：使用API更新您的來源帳戶.

刪除您的資料流

透過對執行DELETE請求來刪除您的資料流 Flow Service API，同時提供您要刪除之資料流的ID做為查詢引數的一部分。如需完整的API範例，請閱讀以下指南：使用API刪除您的資料流.

刪除您的帳戶

向以下網站執行DELETE請求，刪除您的帳戶： Flow Service API，同時提供您要刪除之帳戶的基本連線ID。如需完整的API範例，請閱讀以下指南：使用API刪除您的來源帳戶.

recommendation-more-help

337b99bb-92fb-42ae-b6b7-c7042161d089