共用方式為


Azure Data Factory 和 Azure Synapse Analytics 中的 JSON 格式

適用於:Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory,這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。 了解如何免費開始新的試用

當您想要剖析 JSON 檔案或將資料寫入 JSON 格式時,請遵循本文內容來進行作業。

下列連接器支援 JSON 格式:

資料集屬性

如需可用來定義資料集的區段和屬性完整清單,請參閱資料集一文。 本節提供 JSON 資料集所支援的屬性清單。

屬性 描述 必要
type 資料集的 type 屬性必須設定為 Json Yes
location 檔案的位置設定。 每個檔案型連接器都包含專屬的位置類型,並支援 location 下的屬性。 請參閱連接器文章 -> 資料集屬性一節中的詳細資料 Yes
encodingName 用來讀取/寫入測試檔案的編碼類型。
允許的值如下:"UTF-8"、"UTF-8 不使用 BOM"、"UTF-16"、"UTF-16BE"、"UTF-32"、"UTF-32BE"、"US-ASCII"、"UTF-7"、"BIG5"、"EUC-JP"、"EUC-KR"、"GB2312"、"GB18030"、"JOHAB"、"SHIFT-JIS"、"CP875"、"CP866"、"IBM00858"、"IBM037"、"IBM273"、"IBM437"、"IBM500"、"IBM737"、"IBM775"、"IBM850"、"IBM852"、"IBM855"、"IBM857"、"IBM860"、"IBM861"、"IBM863"、"IBM864"、"IBM865"、"IBM869"、"IBM870"、"IBM01140"、"IBM01141"、"IBM01142"、"IBM01143"、"IBM01144"、"IBM01145"、"IBM01146"、"IBM01147"、"IBM01148"、"IBM01149"、"ISO-2022-JP"、"ISO-2022-KR"、"ISO-8859-1"、"ISO-8859-2"、"ISO-8859-3"、"ISO-8859-4"、"ISO-8859-5"、"ISO-8859-6"、"ISO-8859-7"、"ISO-8859-8"、"ISO-8859-9"、"ISO-8859-13"、"ISO-8859-15"、"WINDOWS-874"、"WINDOWS-1250"、"WINDOWS-1251"、"WINDOWS-1252"、"WINDOWS-1253"、"WINDOWS-1254"、"WINDOWS-1255"、"WINDOWS-1256"、"WINDOWS-1257"、"WINDOWS-1258"。
No
壓縮 設定檔案壓縮的屬性群組。 當您要在活動執行期間執行壓縮/解壓縮時,請設定此區段。 No
type
(compression)
用來讀取/寫入 JSON 檔案的壓縮轉碼器。
允許的值為 bzip2gzipdeflateZipDflateTarGzipTarsnappylz4。 預設為不壓縮。
請注意,複製活動目前不支援 "snappy" 和 "lz4",而對應資料流不支援 "ZipDeflate"、"TarGzip" 和 "Tar"。
請注意,使用複製活動將 ZipDeflate/TarGzip/Tar 檔案解壓縮並寫入檔案型接收資料存放區時,預設會將檔案擷取至資料夾:<path specified in dataset>/<folder named as source compressed file>/,在複製活動來源上使用 preserveZipFileNameAsFolder/preserveCompressionFileNameAsFolder 來控制是否要保留壓縮檔的名稱做為資料夾結構。
否。
level
(compression)
壓縮比。
允許的值為 OptimalFastest
- Fastest:即使產生的檔案不以最佳方式壓縮,也應盡快完成壓縮作業。
- Optimal:即使作業需要較長時間完成,壓縮作業也應以最佳方式壓縮。 如需詳細資訊,請參閱 壓縮層級 主題。
No

下列是 Azure Blob 儲存體上的 JSON 資料集範例:

{
    "name": "JSONDataset",
    "properties": {
        "type": "Json",
        "linkedServiceName": {
            "referenceName": "<Azure Blob Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, retrievable during authoring > ],
        "typeProperties": {
            "location": {
                "type": "AzureBlobStorageLocation",
                "container": "containername",
                "folderPath": "folder/subfolder",
            },
            "compression": {
                "type": "gzip"
            }
        }
    }
}

複製活動屬性

如需可用來定義活動的區段和屬性完整清單,請參閱管線一文。 本節提供 JSON 來源和接收器支援的屬性清單。

了解如何從 JSON 檔案擷取資料,並對應至接收資料存放區/格式,或相反地從結構描述對應中擷取資料。

JSON 做為來源

複製活動的 [來源] 區段支援下列屬性。

屬性 描述 必要
type 複製活動來源的型別屬性必須設定為:JSONSource Yes
formatSettings 屬性群組。 請參閱以下 JSON 讀取設定資料表。 No
storeSettings 屬性群組,可決定從資料存放區讀取資料的方式。 在 storeSettings 下,每個檔案型連接器都包含專屬的支援讀取設定。 請參閱連接器文章 -> 複製活動屬性一節中的詳細資料 No

支援 formatSettings 下的 JSON 讀取設定

屬性 描述 必要
type formatSettings 的型別必須設定為 JsonReadSettings Yes
compressionProperties 關於如何針對指定的壓縮轉碼器解壓縮資料的一組屬性。 No
preserveZipFileNameAsFolder
(compressionProperties->type 下為 ZipDeflateReadSettings)
將輸入資料集設定為使用 ZipDeflate 壓縮時適用。 指出是否要在複製期間保留來源 ZIP 檔案名稱做為資料夾結構。
- 設定為 true (預設) 時,服務會將解壓縮的檔案寫入 <path specified in dataset>/<folder named as source zip file>/
- 設定為 false 時,服務會將解壓縮的檔案直接寫入 <path specified in dataset>。 請確定不同的來源 ZIP 檔案中沒有重複的檔案名稱,以避免發生競爭或非預期的行為。
No
preserveCompressionFileNameAsFolder
(compressionProperties-type> 下為 TarGZipReadSettingsTarReadSettings)
將輸入資料集設定為使用 TarGzip/Tar 壓縮時適用。 指出是否要在複製期間保留來源壓縮檔案名稱做為資料夾結構。
- 設定為 true (預設) 時,服務會將解壓縮的檔案寫入 <path specified in dataset>/<folder named as source compressed file>/
- 設定為 false 時,服務會將解壓縮的檔案直接寫入 <path specified in dataset>。 請確定不同的來源檔案中沒有重複的檔案名稱,以避免發生競爭或非預期的行為。
No

JSON 做為接收

複製活動的 [接收] 區段支援下列屬性。

屬性 描述 必要
type 複製活動來源的 type 屬性必須設定為 JSONSink Yes
formatSettings 屬性群組。 請參閱下方 JSON 寫入設定資料表。 No
storeSettings 屬性群組,可決定將資料寫入資料存放區的方式。 每個以檔案為基礎的連接器在 storeSettings 底下皆具有自身的支援寫入設定。 請參閱連接器文章 -> 複製活動屬性一節中的詳細資料 No

formatSettings 底下的支援 JSON 寫入設定

屬性 描述 必要
type formatSettings 的型別必須設定為 JsonWriteSettings Yes
filePattern 表示每個 JSON 檔案中儲存的資料模式。 允許的值為︰setOfObjects (JSON 行) 和 arrayOfObjects預設值setOfObjects。 關於這些模式的詳細資訊,請參閱 JSON 檔案模式一節。 No

JSON 檔案模式

從 JSON 檔案複製資料時,複製活動可以自動偵測並剖析下列 JSON 檔案的模式。 將資料寫入 JSON 檔案時,您可以在複製活動接收上設定檔案模式。

  • 類型 I:setOfObjects

    每個檔案都包含單一物件、JSON 行或串連物件。

    • 單一物件 JSON 範例

      {
          "time": "2015-04-29T07:12:20.9100000Z",
          "callingimsi": "466920403025604",
          "callingnum1": "678948008",
          "callingnum2": "567834760",
          "switch1": "China",
          "switch2": "Germany"
      }
      
    • JSON 行 (預設為接收)

      {"time":"2015-04-29T07:12:20.9100000Z","callingimsi":"466920403025604","callingnum1":"678948008","callingnum2":"567834760","switch1":"China","switch2":"Germany"}
      {"time":"2015-04-29T07:13:21.0220000Z","callingimsi":"466922202613463","callingnum1":"123436380","callingnum2":"789037573","switch1":"US","switch2":"UK"}
      {"time":"2015-04-29T07:13:21.4370000Z","callingimsi":"466923101048691","callingnum1":"678901578","callingnum2":"345626404","switch1":"Germany","switch2":"UK"}
      
    • 串連的 JSON 範例

      {
          "time": "2015-04-29T07:12:20.9100000Z",
          "callingimsi": "466920403025604",
          "callingnum1": "678948008",
          "callingnum2": "567834760",
          "switch1": "China",
          "switch2": "Germany"
      }
      {
          "time": "2015-04-29T07:13:21.0220000Z",
          "callingimsi": "466922202613463",
          "callingnum1": "123436380",
          "callingnum2": "789037573",
          "switch1": "US",
          "switch2": "UK"
      }
      {
          "time": "2015-04-29T07:13:21.4370000Z",
          "callingimsi": "466923101048691",
          "callingnum1": "678901578",
          "callingnum2": "345626404",
          "switch1": "Germany",
          "switch2": "UK"
      }
      
  • 類型 II:arrayOfObjects

    每個檔案都會包含物件的陣列。

    [
        {
            "time": "2015-04-29T07:12:20.9100000Z",
            "callingimsi": "466920403025604",
            "callingnum1": "678948008",
            "callingnum2": "567834760",
            "switch1": "China",
            "switch2": "Germany"
        },
        {
            "time": "2015-04-29T07:13:21.0220000Z",
            "callingimsi": "466922202613463",
            "callingnum1": "123436380",
            "callingnum2": "789037573",
            "switch1": "US",
            "switch2": "UK"
        },
        {
            "time": "2015-04-29T07:13:21.4370000Z",
            "callingimsi": "466923101048691",
            "callingnum1": "678901578",
            "callingnum2": "345626404",
            "switch1": "Germany",
            "switch2": "UK"
        }
    ]
    

對應資料流程屬性

對應資料流中,您可以在下列資料存放區讀取和寫入 JSON 格式:Azure Blob 儲存體Azure Data Lake Storage Gen1Azure Data Lake Storage Gen2SFTP,而且您可以在 Amazon S3 中讀取 JSON 格式。

來源屬性

下表列出 json 來源所支援的屬性。 您可以在 [來源選項] 索引標籤中編輯這些屬性。

名稱 描述 必要 允許的值 資料流程指令碼屬性
萬用字元路徑 系統會處理符合萬用字元路徑的所有檔案。 覆寫資料集的資料夾和檔案路徑集合。 String[] wildcardPaths
分割區根路徑 如果是分割的檔案資料,您可以輸入分割區根路徑,讀取作為資料行的分割資料夾 String partitionRootPath
檔案清單 您的來源是否指向列出待處理檔案的文字檔 truefalse fileList
儲存檔案名稱的資料行 使用來源檔案名稱和路徑,建立新的資料行 String rowUrlColumn
完成後 處理後刪除或移動檔案。 從容器根開始的檔案路徑 刪除:truefalse
移動:['<from>', '<to>']
purgeFiles
moveFiles
依上次修改日期來篩選 根據上次變更檔案的時間,選擇篩選的檔案 時間戳記 modifiedAfter
modifiedBefore
單一文件 對應資料流會從每個檔案讀取一個 JSON 文件 truefalse singleDocument
未加上引號的資料行名稱 如果選取 [未加上引號的資料行名稱],對應資料流會讀取未以引號括住的 JSON 資料行。 truefalse unquotedColumnNames
有註解 如果 JSON 資料具有 C 或 C++ 樣式註解,請選取 [有註解] truefalse asComments
單引號 讀取未以引號括住的 JSON 資料行 truefalse singleQuoted
反斜線逸出 如果使用反斜線逸出 JSON 資料中的字元,請選取 [反斜線逸出] truefalse backslashEscape
允許找不到任何檔案 如果為 true,找不到檔案時不會擲回錯誤 truefalse ignoreNoFilesFound

內嵌資料集

對應資料流支援「內嵌資料集」作為定義來源和接收的選項。 內嵌 JSON 資料集會直接定義在您的來源和接收轉換內,且不會在定義的資料流程外部共用。 其有助於直接在資料流程內針對資料集屬性進行參數化,並可受益於共用 ADF 資料集帶來的效能提升。

當您要讀取大量的來源資料夾和檔案時,可以在 [投影] | [結構描述選項] 對話方塊內設定 [使用者投影的結構描述] 選項來改善資料流程檔案探索效能。 此選項會關閉 ADF 的預設結構描述自動探索,並將大幅改善檔案探索的效能。 設定此選項之前,請務必匯入 JSON 投影,讓 ADF 具有現有投影結構描述。 此選項不適用於結構描述漂移。

來源格式選項

使用 JSON 資料集做為資料流程中的來源,可讓您設定五個額外的設定。 您可以在 [來源選項] 索引標籤中的 [JSON 設定] 摺疊式功能表底下找到這些設定。針對 [文件表單] 設定,您可以選取 [單一文件]、[每行文件] 及 [文件陣列] 類型的其中一個。

JSON 設定

預設

根據預設,JSON 資料會以下列格式讀取。

{ "json": "record 1" }
{ "json": "record 2" }
{ "json": "record 3" }

單一文件

如果已選取 [單一文件],對應資料流會從每個檔案讀取一個 JSON 文件。

File1.json
{
    "json": "record 1"
}
File2.json
{
    "json": "record 2"
}
File3.json
{
    "json": "record 3"
}

如果已選取 [每行文件],對應資料流會從檔案中的每一行讀取一個 JSON 文件。

File1.json
{"json": "record 1"}

File2.json
 {"time":"2015-04-29T07:12:20.9100000Z","callingimsi":"466920403025604","callingnum1":"678948008","callingnum2":"567834760","switch1":"China","switch2":"Germany"}
 {"time":"2015-04-29T07:13:21.0220000Z","callingimsi":"466922202613463","callingnum1":"123436380","callingnum2":"789037573","switch1":"US","switch2":"UK"}

File3.json
 {"time":"2015-04-29T07:12:20.9100000Z","callingimsi":"466920403025604","callingnum1":"678948008","callingnum2":"567834760","switch1":"China","switch2":"Germany"}
 {"time":"2015-04-29T07:13:21.0220000Z","callingimsi":"466922202613463","callingnum1":"123436380","callingnum2":"789037573","switch1":"US","switch2":"UK"}
 {"time":"2015-04-29T07:13:21.4370000Z","callingimsi":"466923101048691","callingnum1":"678901578","callingnum2":"345626404","switch1":"Germany","switch2":"UK"}

如果已選取 [文件陣列],對應資料流會從檔案讀取文件的單一陣列。

File.json
[
        {
            "time": "2015-04-29T07:12:20.9100000Z",
            "callingimsi": "466920403025604",
            "callingnum1": "678948008",
            "callingnum2": "567834760",
            "switch1": "China",
            "switch2": "Germany"
        },
        {
            "time": "2015-04-29T07:13:21.0220000Z",
            "callingimsi": "466922202613463",
            "callingnum1": "123436380",
            "callingnum2": "789037573",
            "switch1": "US",
            "switch2": "UK"
        },
        {
            "time": "2015-04-29T07:13:21.4370000Z",
            "callingimsi": "466923101048691",
            "callingnum1": "678901578",
            "callingnum2": "345626404",
            "switch1": "Germany",
            "switch2": "UK"
        }
    ]

注意

如果資料流程在預覽 JSON 資料時擲回指出 "corrupt_record" 錯誤,可能是您的資料包含 JSON 檔案中的單一文件。 設定「單一文件」應該能清除該錯誤。

未加上引號的資料行名稱

如果選取 [未加上引號的資料行名稱],對應資料流會讀取未以引號括住的 JSON 資料行。

{ json: "record 1" }
{ json: "record 2" }
{ json: "record 3" }

有註解

如果 JSON 資料具有 C 或 C++ 樣式註解,請選取 [有註解]

{ "json": /** comment **/ "record 1" }
{ "json": "record 2" }
{ /** comment **/ "json": "record 3" }

單引號

如果 JSON 欄位和值使用單引號而不是雙引號,請選取 [單引號]

{ 'json': 'record 1' }
{ 'json': 'record 2' }
{ 'json': 'record 3' }

反斜線逸出

如果使用反斜線逸出 JSON 資料中的字元,請選取 [反斜線逸出]

{ "json": "record 1" }
{ "json": "\} \" \' \\ \n \\n record 2" }
{ "json": "record 3" }

接收屬性

下表列出 json 接收所支援的屬性。 您可以在 [設定] 索引標籤中編輯這些屬性。

名稱 描述 必要 允許的值 資料流程指令碼屬性
清除資料夾 如果在進行寫入之前清除目的地資料夾 truefalse truncate
檔案名稱選項 已寫入資料的命名格式。 依預設,每個分割區的一個檔案會是 part-#####-tid-<guid> 格式 模式:String
每個分割區:String[]
作為資料行中的資料:String
輸出至單一檔案:['<fileName>']
filePattern
partitionFileNames
rowUrlColumn
partitionFileNames

在衍生的資料行中建立 JSON 結構

您可以透過衍生的資料行運算式建立器,將複雜的資料行新增至資料流程。 在衍生的資料行轉換中新增資料行,然後按一下藍色方塊開啟運算式建立器。 若要讓資料行變得複雜,您可以手動輸入 JSON 結構,或使用 UX,以互動方式新增子欄。

使用運算式建立器 UX

在輸出結構描述側邊窗格中,將滑鼠懸停在資料行上,然後按一下加號圖示。 選取 [新增子欄],使資料行成為複雜類型。

新增子資料行

您可以用相同的方式新增其他資料行和子欄。 針對每個非複雜欄位,可以在右邊的運算式編輯器中新增運算式。

新增複雜資料行

手動輸入 JSON 結構

若要手動新增 JSON 結構,請新增資料行,然後在編輯器中輸入運算式。 運算式遵循下列一般格式:

@(
    field1=0,
    field2=@(
        field1=0
    )
)

如果針對名為 "complexColumn" 的資料行輸入此運算式,則會以下列 JSON 形式寫入接收:

{
    "complexColumn": {
        "field1": 0,
        "field2": {
            "field1": 0
        }
    }
}

完整階層式定義的手動指令碼範例

@(
    title=Title,
    firstName=FirstName,
    middleName=MiddleName,
    lastName=LastName,
    suffix=Suffix,
    contactDetails=@(
        email=EmailAddress,
        phone=Phone
    ),
    address=@(
        line1=AddressLine1,
        line2=AddressLine2,
        city=City,
        state=StateProvince,
        country=CountryRegion,
        postCode=PostalCode
    ),
    ids=[
        toString(CustomerID), toString(AddressID), rowguid
    ]
)

以下是一些與 JSON 格式相關的常見連接器和格式: