Azure Data Factory と Synapse Analytics でサポートされるファイル形式と圧縮コーデック (レガシ)

適用対象: Azure Data Factory Azure Synapse Analytics

この記事は、次のコネクタに適用されます。Amazon S3、Azure Blob、Azure Data Lake Storage Gen1、Azure Data Lake Storage Gen2、Azure Files、ファイル システム、FTP、Google Cloud Storage、HDFS、HTTP、SFTP。

テキスト形式 (レガシ)

テキスト ファイルからの読み取りまたはテキスト ファイルへの書き込みを行うには、データセットの format セクション で type プロパティを TextFormat に設定します。 format セクションにオプションのプロパティを指定することもできます。 構成方法については、「TextFormat の例」セクションを参照してください。

TextFormat の例

次のデータセットの JSON 定義では、省略可能なプロパティの一部が指定されます。

"typeProperties":
{
    "folderPath": "mycontainer/myfolder",
    "fileName": "myblobname",
    "format":
    {
        "type": "TextFormat",
        "columnDelimiter": ",",
        "rowDelimiter": ";",
        "quoteChar": "\"",
        "NullValue": "NaN",
        "firstRowAsHeader": true,
        "skipLineCount": 0,
        "treatEmptyAsNull": true
    }
},

quoteChar の代わりに escapeChar を使用するには、quoteChar の含まれる行を次の escapeChar で置き換えます。

"escapeChar": "$",

firstRowAsHeader と skipLineCount を使用するシナリオ

• ファイル以外のソースからテキスト ファイルにコピーし、スキーマ メタデータ(例:SQL スキーマ) を含むヘッダー行を追加する。 このシナリオでは、出力データセットの firstRowAsHeader を True として指定します。
• ヘッダー行を含むテキスト ファイルから、ファイル以外のシンクにコピーし、その行を削除する: 入力データセットの firstRowAsHeader を True として指定します。
• テキスト ファイルからコピーして、データやヘッダー情報を含まない先頭の数行をスキップする: skipLineCount を指定して、スキップする行数を示します。 ファイルの残りの部分にヘッダー行が含まれている場合は、firstRowAsHeader も指定できます。 skipLineCount と firstRowAsHeader の両方を指定した場合は、まず行がスキップされ、次に入力ファイルからヘッダー情報が読み取られます。

JSON 形式 (レガシ)

Azure Cosmos DB との間で JSON ファイルをそのままインポート/エクスポートする場合は、Azure Cosmos DB との間でのデータの移動に関する記事の「Import/export JSON documents (JSON ドキュメントのインポート/エクスポート)」のセクションをご覧ください。

JSON ファイルを解析するか、JSON 形式でデータを書き込む場合は、format セクションの type プロパティを JsonFormat に設定します。 format セクションにオプションのプロパティを指定することもできます。 構成方法については、「JsonFormat の例」セクションを参照してください。

JSON ファイルのパターン

コピー アクティビティでは、次の JSON ファイルのパターンを解析することができます。

• タイプ I: setOfObjects

  各ファイルには、単一のオブジェクト、または改行区切り/連結された複数のオブジェクトが含まれます。 出力データセットでこのオプションを選択すると、コピー アクティビティによって、各オブジェクトが行ごとに配置された (改行区切り) 1 つの 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"
      }
  ]
  

JsonFormat の例

ケース 1:JSON ファイルからのデータのコピー

サンプル 1: オブジェクトと配列からデータを抽出する

このサンプルでは、1 つのルート JSON オブジェクトが表形式の結果の 1 つのレコードにマップされることを想定しています。 次の内容が含まれる JSON ファイルをお持ちで、

{
    "id": "ed0e4960-d9c5-11e6-85dc-d7996816aad3",
    "context": {
        "device": {
            "type": "PC"
        },
        "custom": {
            "dimensions": [
                {
                    "TargetResourceType": "Microsoft.Compute/virtualMachines"
                },
                {
                    "ResourceManagementProcessRunId": "827f8aaa-ab72-437c-ba48-d8917a7336a3"
                },
                {
                    "OccurrenceTime": "1/13/2017 11:24:37 AM"
                }
            ]
        }
    }
}

オブジェクトと配列両方からデータを抽出することで、上記の内容を次の形式の Azure SQL テーブルにコピーします。

JsonFormat 型の入力データセットは次のように定義されます (関連する部分のみでの部分的な定義)。 具体的には次のとおりです。

• structure セクションでは、表形式データへの変換中に、カスタマイズされた列名と、対応するデータ型を定義します。 このセクションは、列マッピングを行う必要がない場合は省略可能です。 詳しくは、変換先のデータセット列へのソース データセット列のマップに関するページをご覧ください。
• jsonPathDefinition は、データを抽出する位置を示す各列の JSON のパスを指定します。 配列からデータをコピーするには、array[x].property を使用して xth 番目のオブジェクトから特定のプロパティの値を抽出するか、array[*].property を使用してこのようなプロパティを含むオブジェクトから値を見つけることができます。

"properties": {
    "structure": [
        {
            "name": "id",
            "type": "String"
        },
        {
            "name": "deviceType",
            "type": "String"
        },
        {
            "name": "targetResourceType",
            "type": "String"
        },
        {
            "name": "resourceManagementProcessRunId",
            "type": "String"
        },
        {
            "name": "occurrenceTime",
            "type": "DateTime"
        }
    ],
    "typeProperties": {
        "folderPath": "mycontainer/myfolder",
        "format": {
            "type": "JsonFormat",
            "filePattern": "setOfObjects",
            "jsonPathDefinition": {"id": "$.id", "deviceType": "$.context.device.type", "targetResourceType": "$.context.custom.dimensions[0].TargetResourceType", "resourceManagementProcessRunId": "$.context.custom.dimensions[1].ResourceManagementProcessRunId", "occurrenceTime": " $.context.custom.dimensions[2].OccurrenceTime"}
        }
    }
}

サンプル 2: 同じパターンの複数のオブジェクトを配列からクロス適用する

このサンプルでは、表形式の結果において 1 つのルート JSON オブジェクトを複数のレコードに変換することを想定しています。 次の内容が含まれる JSON ファイルをお持ちで、

{
    "ordernumber": "01",
    "orderdate": "20170122",
    "orderlines": [
        {
            "prod": "p1",
            "price": 23
        },
        {
            "prod": "p2",
            "price": 13
        },
        {
            "prod": "p3",
            "price": 231
        }
    ],
    "city": [ { "sanmateo": "No 1" } ]
}

配列内のデータをフラット化し、共通のルート情報とクロス結合させることで Azure SQL テーブルに次の形式でコピーする場合:

JsonFormat 型の入力データセットは次のように定義されます (関連する部分のみでの部分的な定義)。 具体的には次のとおりです。

• structure セクションでは、表形式データへの変換中に、カスタマイズされた列名と、対応するデータ型を定義します。 このセクションは、列マッピングを行う必要がない場合は省略可能です。 詳しくは、変換先のデータセット列へのソース データセット列のマップに関するページをご覧ください。
• jsonNodeReference は、orderlines という配列の直下にある同じパターンのオブジェクトからのデータの反復処理と抽出を行うことを示します。
• jsonPathDefinition は、データを抽出する位置を示す各列の JSON のパスを指定します。 この例での ordernumber、orderdate、city は、$. から始まる JSON のパスが含まれるルート オブジェクトの直下にあります。order_pd と order_price は、$. のない配列要素から派生したパスで定義されています。

"properties": {
    "structure": [
        {
            "name": "ordernumber",
            "type": "String"
        },
        {
            "name": "orderdate",
            "type": "String"
        },
        {
            "name": "order_pd",
            "type": "String"
        },
        {
            "name": "order_price",
            "type": "Int64"
        },
        {
            "name": "city",
            "type": "String"
        }
    ],
    "typeProperties": {
        "folderPath": "mycontainer/myfolder",
        "format": {
            "type": "JsonFormat",
            "filePattern": "setOfObjects",
            "jsonNodeReference": "$.orderlines",
            "jsonPathDefinition": {"ordernumber": "$.ordernumber", "orderdate": "$.orderdate", "order_pd": "prod", "order_price": "price", "city": " $.city"}
        }
    }
}

以下の点に注意してください。

• structure と jsonPathDefinition がデータセット内で定義されていない場合、コピー アクティビティでは最初のオブジェクトからスキーマを検出し、オブジェクト全体をフラット化します。
• JSON 入力に配列がある場合、コピー アクティビティは既定で配列値全体を文字列に変換します。 jsonNodeReference と jsonPathDefinition の両方またはどちらかからデータを抽出するか、jsonPathDefinition でこれを指定せずにスキップすることが可能です。
• 同じレベルに重複する名前がある場合、コピー アクティビティでは最後の 1 つが選択されます。
• プロパティ名では大文字と小文字が区別されます。 名前は同じでも大文字小文字が異なる 2 つのプロパティは、2 つの個別のプロパティとして扱われます。

ケース 2:JSON ファイルへのデータの書き込み

SQL Database 内に次のテーブルが含まれているとします。

また、レコードごとに、次の形式で JSON オブジェクトに書き込みます。

{
    "id": "1",
    "order": {
        "date": "20170119",
        "price": 2000,
        "customer": "David"
    }
}

JsonFormat 型の出力データセットは次のように定義されます (関連する部分のみでの部分的な定義)。 具体的には、structure セクションでは、目的のファイル内のカスタマイズされたプロパティ名を定義します。nestingSeparator (既定では ".") は、入れ子のレイヤーを名前から識別するために使用されます。 このセクションは、ソース列名と比較してプロパティ名を変更したり、一部のプロパティを入れ子にしたりする必要がない場合は省略可能です。

"properties": {
    "structure": [
        {
            "name": "id",
            "type": "String"
        },
        {
            "name": "order.date",
            "type": "String"
        },
        {
            "name": "order.price",
            "type": "Int64"
        },
        {
            "name": "order.customer",
            "type": "String"
        }
    ],
    "typeProperties": {
        "folderPath": "mycontainer/myfolder",
        "format": {
            "type": "JsonFormat"
        }
    }
}

Parquet 形式 (レガシ)

Parquet ファイルを解析するか、Parquet 形式でデータを書き込む場合は、formattype プロパティを ParquetFormat に設定します。 typeProperties セクション内の Format セクションにプロパティを指定する必要はありません。 例:

"format":
{
    "type": "ParquetFormat"
}

以下の点に注意してください。

• 複雑なデータ型はサポートされていません (MAP、LIST)。
• 列名では、空白はサポートされません。
• Parquet ファイルには、圧縮関連のオプションとして、NONE、SNAPPY、GZIP、LZO があります。 サービスでは、LZO を除く、これらすべての圧縮形式の Parquet ファイルからデータを読み取ることができます。データの読み取りには、メタデータ内の圧縮コーデックが使用されます。 ただし、サービスで Parquet ファイルに書き込むときは、Parquet 形式の既定の動作である SNAPPY が選択されます。 現時点でこの動作をオーバーライドするオプションはありません。

Parquet ファイルのシリアル化/逆シリアル化を使用してセルフホステッド IR 上で実行されるコピーでは、サービスは最初に JRE のレジストリ (SOFTWARE\JavaSoft\Java Runtime Environment\{Current Version}\JavaHome) を調べ、見つからない場合は次に OpenJDK のシステム変数 JAVA_HOME を調べることで、Java ランタイムを見つけます。

• JRE を使用する場合:64 ビット IR には 64 ビット JRE が必要です。 こちらから入手できます。
• OpenJDK を使用する場合: IR バージョン 3.13 以降でサポートされています。 jvm.dll を他のすべての必要な OpenJDK のアセンブリと共にセルフホステッド IR マシンにパッケージ化し、それに応じてシステム環境変数 JAVA_HOME を設定します。

例: 変数 _JAVA_OPTIONS を設定して、値 -Xms256m -Xmx16g を指定します。 フラグ Xms では、Java 仮想マシン (JVM) の初期メモリ割り当てプールを指定します。Xmx では、最大メモリ割り当てプールを指定します。 これは、JVM 起動時のメモリ量が Xms、使用可能なメモリ量が最大で Xmx であることを意味します。 既定では、サービスにより最小で 64MB、最大で 1G が使用されます。

Parquet ファイルのデータ型マッピング

ORC 形式 (レガシ)

ORC ファイルを解析するか、ORC 形式でデータを書き込む場合は、formattype プロパティを OrcFormat に設定します。 typeProperties セクション内の Format セクションにプロパティを指定する必要はありません。 例:

"format":
{
    "type": "OrcFormat"
}

以下の点に注意してください。

• 複雑なデータ型はサポートされていません (STRUCT、MAP、LIST、UNION)。
• 列名では、空白はサポートされません。
• ORC ファイルには、圧縮関連のオプションとして、NONE、ZLIB、SNAPPY の 3 つがあります。 サービスでは、これらすべての圧縮形式の ORC ファイルからデータを読み取ることができます。 データの読み取りには、メタデータ内の圧縮コーデックが使用されます。 ただし、サービスで ORC ファイルに書き込むときは、ORC の既定の動作である ZLIB が選択されます。 現時点でこの動作をオーバーライドするオプションはありません。

ORC ファイルのシリアル化または逆シリアル化を使用してセルフホステッド IR 上で実行されるコピーでは、サービスは最初に JRE のレジストリ (SOFTWARE\JavaSoft\Java Runtime Environment\{Current Version}\JavaHome) を調べ、見つからない場合は次に OpenJDK のシステム変数 JAVA_HOME を調べることで、Java ランタイムを見つけます。

• JRE を使用する場合:64 ビット IR には 64 ビット JRE が必要です。 こちらから入手できます。
• OpenJDK を使用する場合: IR バージョン 3.13 以降でサポートされています。 jvm.dll を他のすべての必要な OpenJDK のアセンブリと共にセルフホステッド IR マシンにパッケージ化し、それに応じてシステム環境変数 JAVA_HOME を設定します。

ORC ファイルデータ型マッピング

AVRO 形式 (レガシ)

Avro ファイルを解析するか、Avro 形式でデータを書き込む場合は、formattype プロパティを AvroFormat に設定します。 typeProperties セクション内の Format セクションにプロパティを指定する必要はありません。 例:

"format":
{
    "type": "AvroFormat",
}

Hive テーブルで Avro 形式を使用するには、Apache Hive のチュートリアルを参照してください。

以下の点に注意してください。

• 複合データ型はサポートされていません (レコード、列挙型、配列、マップ、共用体、および固定)。

圧縮のサポート (レガシ)

このサービスでは、コピー中のデータの圧縮/圧縮解除がサポートされます。 compression プロパティを入力データセットで指定すると、コピー アクティビティでソースから圧縮データを読み取り、圧縮を解除することができます。このプロパティを出力データセットで指定すると、コピー アクティビティによりシンクへの書き込みデータを圧縮することができます。 いくつかのサンプル シナリオを次に示します。

• Azure BLOB から GZIP 圧縮データを読み取って展開し、生成されたデータを Azure SQL Database に書き込みます。 compressiontype プロパティを使用して、Azure BLOB 入力データセットを GZIP として定義します。
• オンプレミスのファイル システムのプレーンテキスト ファイルからデータを読み取り、GZip 形式で圧縮して、圧縮データを Azure BLOB に書き込みます。 compressiontype プロパティを使用して、Azure BLOB 出力データセットを GZip として定義します。
• FTP サーバーから .zip ファイルを読み取り、圧縮解除して中にあるファイルを取得し、それらのファイルを Azure Data Lake Store に格納します。 compressiontype プロパティを使用して、FTP 入力データセットを ZipDeflate として定義します。
• Azure BLOB から GZIP 圧縮データを読み取って展開し、BZIP2 で圧縮して、生成されたデータを Azure BLOB に書き込みます。 Azure BLOB 入力データセットは compressiontype を GZIP に設定して定義し、Azure BLOB 出力データセットは compressiontype を BZIP2 に設定して定義します。

データセットの圧縮を指定するには、次の例のように、データセットの JSON で compression プロパティを使用します。

{
    "name": "AzureBlobDataSet",
    "properties": {
        "type": "AzureBlob",
        "linkedServiceName": {
            "referenceName": "StorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "fileName": "pagecounts.csv.gz",
            "folderPath": "compression/file/",
            "format": {
                "type": "TextFormat"
            },
            "compression": {
                "type": "GZip",
                "level": "Optimal"
            }
        }
    }
}

compression セクションには次の 2 つのプロパティがあります。

• Type: 圧縮コーデックです。GZIP、Deflate、BZIP2、または ZipDeflate を選択できます。 コピー アクティビティを使用して ZipDeflate ファイルを展開し、ファイル ベースのシンク データ ストアに書き込むと、<path specified in dataset>/<folder named as source zip file>/ フォルダーにファイルが抽出されます。

• level: 圧縮率です。Optimal または Fastest を指定できます。

  • Fastest: 圧縮操作は可能な限り短時間で完了しますが、圧縮後のファイルが最適に圧縮されていない場合があります。

  • Optimal:圧縮操作で最適に圧縮されますが、操作が完了するまでに時間がかかる場合があります。

    詳細については、 圧縮レベル に関するトピックをご覧ください。

サポートされていないファイル形式と圧縮形式

拡張機能を使用して、サポートされていないファイルを変換することができます。 Azure Function、および Azure Batch を使用することによるカスタム タスクという 2つのオプションがあります。

Azure Function を使用して tar ファイルの内容を抽出するサンプルをご覧いただけます。 詳細については、「Azure Functions アクティビティ」をご覧ください。

また、カスタム dotnet アクティビティを使用してこの機能性を構築することもできます。 詳細については、ここを参照してください。

関連するコンテンツ

サポートされるファイル形式と圧縮の記事で最新のサポートされるファイル形式と圧縮を確認します。