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

發行項
05/15/2024

適用於：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 檔案的壓縮轉碼器。允許的值為 bzip2、gzip、deflate、ZipDflate、TarGzip、Tar、snappy 或 lz4。預設為不壓縮。請注意，複製活動目前不支援 "snappy" 和 "lz4"，而對應資料流不支援 "ZipDeflate"、"TarGzip" 和 "Tar"。請注意，使用複製活動將 ZipDeflate/TarGzip/Tar 檔案解壓縮並寫入檔案型接收資料存放區時，預設會將檔案擷取至資料夾：`<path specified in dataset>/<folder named as source compressed file>/`，在複製活動來源上使用 `preserveZipFileNameAsFolder`/`preserveCompressionFileNameAsFolder` 來控制是否要保留壓縮檔的名稱做為資料夾結構。	否。
level (在 `compression` 下)	壓縮比。允許的值為 Optimal 或 Fastest。 - 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`> 下為 `TarGZipReadSettings` 或 `TarReadSettings`)	將輸入資料集設定為使用 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 Gen1、Azure Data Lake Storage Gen2 和 SFTP，而且您可以在 Amazon S3 中讀取 JSON 格式。

來源屬性

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

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

名稱	描述	必要	允許的值	資料流程指令碼屬性
清除資料夾	如果在進行寫入之前清除目的地資料夾	否	`true` 或 `false`	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 格式相關的常見連接器和格式：

共用方式為

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

資料集屬性

複製活動屬性

JSON 做為來源

JSON 做為接收

JSON 檔案模式

對應資料流程屬性

來源屬性

內嵌資料集

來源格式選項

預設

單一文件

未加上引號的資料行名稱

有註解

單引號

反斜線逸出

接收屬性

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

使用運算式建立器 UX

手動輸入 JSON 結構

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

意見反應

其他資源

共用方式為

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

資料集屬性

複製活動屬性

JSON 做為來源

JSON 做為接收

JSON 檔案模式

對應資料流程屬性

來源屬性

內嵌資料集

來源格式選項

預設

單一文件

未加上引號的資料行名稱

有註解

單引號

反斜線逸出

接收屬性

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

使用運算式建立器 UX

手動輸入 JSON 結構

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

相關的連接器和格式

相關內容

意見反應

其他資源