檔案格式設定

Destination SDK支援一組彈性的功能,您可以根據整合需求進行設定。 這些功能中包括CSV檔案格式化的支援。

當您透過Destination SDK建立以檔案為基礎的目的地時,可以定義匯出的CSV檔案的格式設定。 您可以自訂許多格式選項,例如但不限於:

  • CSV檔案是否應該包含標題;
  • 引號值要使用的字元;
  • 空值應該是什麼樣子。

視您的目的地設定而定,使用者在連線至檔案式目的地時,會在UI中看到某些選項。 您可以在檔案型目的地的檔案格式選項檔案中看到這些選項的樣子。

檔案格式設定是以檔案為基礎的目的地,屬於目的地伺服器組態的一部分。

若要瞭解此元件在何處適合使用Destination SDK建立的整合,請參閱設定選項檔案中的圖表,或參閱如何使用Destination SDK設定檔案型目的地的指南。

您可以透過/authoring/destination-servers端點設定檔案格式選項。 請參閱下列API參考頁面,以取得詳細的API呼叫範例,您可在此範例設定本頁面中顯示的元件。

此頁面說明已匯出CSV個檔案的所有支援檔案格式設定。

IMPORTANT
Destination SDK支援的所有引數名稱和值都區分大小寫​**​**。 為避免區分大小寫錯誤,請完全依照檔案中所示使用引數名稱和值。

支援的整合型別 supported-integration-types

如需瞭解哪些型別的整合支援本頁面所述功能的詳細資訊,請參閱下表。

整合型別
支援功能
即時(串流)整合
檔案式(批次)整合

支援的引數 supported-parameters

您可以修改匯出檔案的數個屬性,以符合目的地檔案接收系統的需求,以最佳方式讀取和解譯從Experience Platform接收的檔案。

NOTE
只有在匯出CSV檔案時才支援CSV選項。 設定新的目的地伺服器時,fileConfigurations區段不是強制性的。 如果您沒有在API呼叫中為CSV選項傳遞任何值,則會使用位於🔗下方參考表格中的預設值。

使用者無法選取組態選項的CSV選項 file-configuration-templating-none

在以下的設定範例中,所有CSV選項皆為預先定義。 每個csvOptions引數中定義的匯出設定都是最終設定,使用者無法加以修改。

"fileConfigurations": {
        "compression": {
            "templatingStrategy": "PEBBLE_V1",
            "value": "{{customerData.compression}}"
        },
        "fileType": {
            "templatingStrategy": "PEBBLE_V1",
            "value": "{{customerData.fileType}}"
        },
        "csvOptions": {
            "quote": {
                "templatingStrategy": "NONE",
                "value": "\""
            },
            "quoteAll": {
                "templatingStrategy": "NONE",
                "value": "false"
            },
            "escape": {
                "templatingStrategy": "NONE",
                "value": "\\"
            },
            "escapeQuotes": {
                "templatingStrategy": "NONE",
                "value": "true"
            },
            "header": {
                "templatingStrategy": "NONE",
                "value": "true"
            },
            "ignoreLeadingWhiteSpace": {
                "templatingStrategy": "NONE",
                "value": "true"
            },
            "ignoreTrailingWhiteSpace": {
                "templatingStrategy": "NONE",
                "value": "true"
            },
            "nullValue": {
                "templatingStrategy": "NONE",
                "value": ""
            },
            "dateFormat": {
                "templatingStrategy": "NONE",
                "value": "yyyy-MM-dd"
            },
            "timestampFormat": {
                "templatingStrategy": "NONE",
                "value": "yyyy-MM-dd'T':mm:ss[.SSS][XXX]"
            },
            "charToEscapeQuoteEscaping": {
                "templatingStrategy": "NONE",
                "value": "\\"
            },
            "emptyValue": {
                "templatingStrategy": "NONE",
                "value": ""
            }
        },
        "maxFileRowCount":5000000,
        "includeFileManifest": {
            "templatingStrategy":"PEBBLE_V1",
            "value":"{{ customerData.includeFileManifest }}"
      }
    }

CSV選項,使用者可從中選取設定選項 file-configuration-templating-pebble

在以下的設定範例中,並未預先定義任何CSV選項。 每個csvOptions引數中的value是透過/destinations端點在對應的客戶資料欄位中設定的(例如quote檔案格式選項的customerData.quote),使用者可以使用Experience PlatformUI在您對應該客戶資料欄位中設定的各種選項之間選取。 您可以在檔案型目的地的檔案格式選項檔案中看到這些選項的樣子。

{
   "fileConfigurations":{
      "compression":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{% if customerData contains 'compression' and customerData.compression is not empty %}{{customerData.compression}}{% else %}NONE{% endif %}"
      },
      "fileType":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.fileType}}"
      },
      "csvOptions":{
         "sep":{
            "templatingStrategy":"PEBBLE_V1",
            "value":"{% if customerData contains 'csvOptions' and customerData.csvOptions contains 'delimiter' %}{{customerData.csvOptions.delimiter}}{% else %},{% endif %}"
         },
         "quote":{
            "templatingStrategy":"PEBBLE_V1",
            "value":"{% if customerData contains 'csvOptions' and customerData.csvOptions contains 'quote' %}{{customerData.csvOptions.quote}}{% else %}\"{% endif %}"
         },
         "escape":{
            "templatingStrategy":"PEBBLE_V1",
            "value":"{% if customerData contains 'csvOptions' and customerData.csvOptions contains 'escape' %}{{customerData.csvOptions.escape}}{% else %}\\{% endif %}"
         },
         "nullValue":{
            "templatingStrategy":"PEBBLE_V1",
            "value":"{% if customerData contains 'csvOptions' and customerData.csvOptions contains 'nullValue' %}{{customerData.csvOptions.nullValue}}{% else %}null{% endif %}"
         },
         "emptyValue":{
            "templatingStrategy":"PEBBLE_V1",
            "value":"{% if customerData contains 'csvOptions' and customerData.csvOptions contains 'emptyValue' %}{{customerData.csvOptions.emptyValue}}{% else %}{% endif %}"
         }
      },
      "maxFileRowCount":5000000,
      "includeFileManifest": {
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{ customerData.includeFileManifest }}"
      }
   }
}

支援的檔案格式選項完整參考和範例 file-formatting-reference-and-example

TIP
CSV檔案的Apache Spark指南也記載了下述的CSV檔案格式選項。 以下使用的說明取自Apache Spark指南。

以下是Destination SDK中所有可用檔案格式選項的完整參考,連同每個選項的輸出範例。

欄位
必要/選用
說明
預設值
範例輸出1
範例輸出2
templatingStrategy
必要

對於您設定的每個檔案格式選項,您必須新增引數templatingStrategy,其可以有兩個值:

  • NONE:如果您不打算允許使用者在設定的不同值之間選取,請使用此值。 請參閱此組態,以取得檔案格式選項固定的範例。
  • PEBBLE_V1:如果您要允許使用者在不同的設定值之間選取,請使用此值。 在此情況下,您也必須在/destination端點設定中設定對應的客戶資料欄位,以在UI中向使用者呈現各種選項。 請參閱此組態的範例,使用者可以在不同的檔案格式選項值之間選取。
-
-
-
compression.value
選填
將資料儲存至檔案時使用的壓縮轉碼器。 支援的值: nonebzip2gziplz4snappy
none
-
-
fileType.value
選填
指定輸出檔案格式。 支援的值: csvparquetjson
csv
-
-
csvOptions.quote.value
選填
只適用於"fileType.value": "csv"。 設定用於逸出引號值的單一字元,其中分隔符號可以是值的一部分。
null
預設值範例: quote.value: "u0000" —> male,NULJohn,LastNameNUL
自訂範例: quote.value: "\"" —> male,"John,LastName"
csvOptions.quoteAll.value
選填
只適用於"fileType.value": "csv"。 指示是否所有值都一律以引號括住。 預設為僅逸出包含引號字元的值。
false
quoteAllfalse —> male,John,"TestLastName"
quoteAlltrue —>"male","John","TestLastName"
csvOptions.delimiter.value
選填
只適用於"fileType.value": "csv"。 為每個欄位和值設定分隔符號。 此分隔符號可為一或多個字元。
,
delimiter, —> comma-separated values"
delimiter\t —> tab-separated values
csvOptions.escape.value
選填
只適用於"fileType.value": "csv"。 設定用來逸出已加引號之值內的引號的單一字元。
\
"escape""\\" —> male,John,"Test,\"LastName5"
"escape""'" —> male,John,"Test,'''"LastName5"
csvOptions.escapeQuotes.value
選填
只適用於"fileType.value": "csv"。 指示是否一律將包含引號的值括在引號中。 預設為逸出包含引號字元的所有值。
true
-
-
csvOptions.header.value
選填
只適用於"fileType.value": "csv"。 指示是否將欄名稱寫入匯出檔案的第一行。
true
-
-
csvOptions.ignoreLeadingWhiteSpace.value
選填
只適用於"fileType.value": "csv"。 指示是否從值中修剪前導空格。
true
ignoreLeadingWhiteSpacetrue —> "male","John","TestLastName"
ignoreLeadingWhiteSpacefalse—> " male","John","TestLastName"
csvOptions.ignoreTrailingWhiteSpace.value
選填
只適用於"fileType.value": "csv"。 指示是否從值修剪尾端空格。
true
ignoreTrailingWhiteSpacetrue —> "male","John","TestLastName"
ignoreTrailingWhiteSpacefalse—> "male ","John","TestLastName"
csvOptions.nullValue.value
選填
只適用於"fileType.value": "csv"。 設定null值的字串表示。
""
nullvalue"" —> male,"",TestLastName
nullvalue"NULL" —> male,NULL,TestLastName
csvOptions.dateFormat.value
選填
只適用於"fileType.value": "csv"。 指示日期格式。
yyyy-MM-dd
dateFormatyyyy-MM-dd —> male,TestLastName,John,2022-02-24
dateFormatMM/dd/yyyy —> male,TestLastName,John,02/24/2022
csvOptions.timestampFormat.value
選填
只適用於"fileType.value": "csv"。 設定表示時間戳記格式的字串。
yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
-
-
csvOptions.charToEscapeQuoteEscaping.value
選填
只適用於"fileType.value": "csv"。 設定用於逸出引號字元的單一字元。
當逸出和引號字元不同時,\。 當逸出和引號字元相同時,\0
-
-
csvOptions.emptyValue.value
選填
只適用於"fileType.value": "csv"。 設定空值的字串表示。
""
"emptyValue":"" --> male,"",John
"emptyValue":"empty" --> male,empty,John
maxFileRowCount
選填
表示每個匯出檔案的最大列數,介於1,000,000到10,000,000列之間。
5,000,000
includeFileManifest
選填
啟用匯出檔案資訊清單與檔案匯出的支援。 資訊清單JSON檔案包含有關匯出位置、匯出大小等的資訊。 資訊清單的命名格式為manifest-<<destinationId>>-<<dataflowRunId>>.json

檢視範例資訊清單檔案。 資訊清單檔案包含下列欄位:

  • flowRunId:產生匯出檔案的資料流執行
  • scheduledTime:檔案匯出的時間(UTC)。
  • exportResults.sinkPath:存放匯出檔案之存放位置中的路徑。
  • exportResults.name:匯出的檔案名稱。
  • size:匯出的檔案大小(位元組)。

後續步驟 next-steps

閱讀本文後,您應該更瞭解檔案格式設定在目標伺服器設定中的運作方式,以及如何進行設定。

若要深入瞭解其他目的地伺服器元件,請參閱下列文章:

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6