Amazon S3マニフェストファイル詳解:QuickSightでサポートされているファイル取り込み指定方法 #quicksight #23 | Amazon QuickSight Advent Calendar 2016

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

当エントリは『Amazon QuickSight Advent Calendar 2016』の23本目のエントリです。

昨日の22本目のエントリは『データソースに関する制限』でした。

『AWS re:Invent 2016』の直前に一般利用可能となったAWSによるBIサービス、Amazon QuickSight。発表されたばかりですが、早速Amazon QuickSightを使い倒すべく色々な切り口でその内容について見て行きたいと思います。

23本目となる当エントリでは、Amazon QuickSightにおける『QuickSightでサポートされているファイル取り込み指定方法』について見て行きたいと思います。

Amaozn QuickSightではJSONマニフェストファイルを使ってAmazon S3のファイルを指定し、インポートを行う事が出来ます。これらのJSONマニフェストについては後述する形式を使用する事が出来ます。形式はAmazon QuickSight形式/Amazon Redshift形式の2つがあります。

Amazon QuickSightマニフェストファイルを使用する場合、拡張子:jsonが必要です(例:my_manifest.json)。Amazon Redshiftマニフェストファイルを使用する場合は任意の拡張子を付ける事が可能です。Amazon Redshiftマニフェストファイルを使用している場合、Amazon Redshiftと同様にAmazon QuickSightはオプションの必須フラグを処理しインポートプロセスを実施、関連付けられたファイルが見つからない場合はエラーを返します。

インポートするファイルについては任意の区切り文字を使用したファイル(*.CSV, *.TSV)、ログ(*.clf)、拡張ログ(*.elf)のいずれかである必要があります。また1つのマニフェストファイルで扱うファイルの拡張子は1つに統一しなければなりません(混在不可)。

マニフェストで指定されたファイルは1GBを超えることはできず、指定されたすべてのファイルの合計サイズは10GBを超えることはできず、指定されたファイルの総数は100を超えることはできません。

指定したファイルは、Amazon QuickSightへのアクセスを許可したAmazon S3バケット内にある必要があります。 AWSリソースへのAmazon QuickSightアクセスの許可については、下記をご参照ください。

Amazon QuickSightマニフェストファイルフォーマット

Amazon QuickSightマニフェストファイルのJSONフォーマットは以下の形式となります。

{ 
    "fileLocations": [                                                    
          {"URIs": ["uri1", "uri2", "uri3"]},
          {"URIPrefixes": ["prefix1", "prefix2", "prefix3"]}
     ],
     "globalUploadSettings": { 
         "format": "CSV",  
         "delimiter": ",",         
         "textqualifier": "'",    
         "containsHeader": "true" 
    }
}

fileLocations エレメントにてインポートするファイルを指定、globalUploadSettings エレメントにてインポートするファイルに関する設定(区切り文字など)を指定します。

マニフェストファイルの各種エレメントの詳細な内容は以下の通りです。

fileLocations

インポート対象のファイルを指定する箇所。URIsまたはURIPrefixesの配列を利用する事が出来ます。少なくとも1つの値を指定する必要があります。

URIs

インポート対象のファイルをURIのリスト形式で指定。Amazon QuickSightはAmazon どのリージョンのS3のファイルにもアクセスする事が出来ますが、Amazon QuickSightアカウントが使われているリージョンとバケットのリージョンが異なる場合、Amazon S3バケットのリージョンを指し示すURIフォーマットを使わなければなりません。利用可能なURIsのフォーマットは以下の通りです。

URIフォーマット 備考
https://s3.amazonaws.com/<bucket name>/<file name> https://s3.amazonaws.com/data_bucket/data.csv
s3://<bucket name>/<file name> s3://data_bucket/data.csv
https://<bucket name>.s3.amazonaws.com/<file name> https://data_bucket.s3.amazonaws.com/data.csv
https://s3-<region name>.amazonaws.com/<bucket name>/<file name> https://s3-us-east-1.amazonaws.com/data_bucket/data.csv (※1)
https://<bucket name>.s3-<region name>.amazonaws.com/<file name> https://data_bucket.s3-us-east-1.amazonaws.com/data.csv (※1)

(※1):このURIタイプは、Amazon S3バケットの領域を識別します。

URIPrefixes

S3バケットのURIの一覧にこの配列を使用します。

指定されたバケット内全てのファイルがインポートされます。Amazon QuickSightは子フォルダのファイル群を再帰的には取得しません(ので気を付けて下さい)。Amazon QuickSightは全リージョンのAmazon S3バケットにアクセス可能です。しかし、Amazon QuickSightのアカウントとリージョンが異なる場合は、この値にはリージョンを指し示すフォーマットを指定する必要があります。サポートされているURIPrefixesのフォーマットは以下の通りです。

URIフォーマット 備考
https://s3.amazonaws.com/<bucket name>/ https://s3.amazonaws.com/data_bucket/
https://s3.amazonaws.com/<bucket name>/<folder name1>/(<folder name2>/etc.) https://s3.amazonaws.com/data_bucket/folder1/
s3://<bucket name> s3://data_bucket/
s3://<bucket name>/<folder name1>/(<folder name2>/etc.) s3://data_bucket/folder1/
https://<bucket name>.s3.amazonaws.com https://data_bucket.s3.amazonaws.com
https://s3-<region name>.amazonaws.com/<bucket name>/ https://s3-us-east-1.amazonaws.com/data_bucket/ (※1)
https://s3-<region name>.amazonaws.com/<bucket name>/<folder name1>/(<folder name2gt;/etc.) https://s3-us-east-1.amazonaws.com/data_bucket/folder1/ (※1)
https://<bucket name>.s3-<region name>.amazonaws.com https://data_bucket.s3-us-east-1.amazonaws.com (※1)

(※1):このURIPrefixタイプは、Amazon S3バケットの領域を識別します。

globalUploadSettings

(オプション)この要素は、Amazon S3ファイルに対するインポート設定(区切り文字等)を指定する際に使用します。もし要素が指定されていない場合、Amazon QuickSightは以下項目毎に定められているデフォルト値を使用します。

重要:
ログファイル(*.clf)、拡張ログファイル(*.elf)については、"format"フィールドのみ利用可能です。これらのファイルを扱う場合、その他のフィールド値は指定しても無視されます。

format

(オプション)インポート対象ファイルの形式を指定。有効な値はCSV, TSV, CLF, ELF。(※デフォルト値:CSV)

delimiter

(オプション)ファイルの区切り文字を指定。[format]フィールドで指定されたファイルタイプと対応している必要があります。有効な形式はCSV形式の場合はカンマ(,)、TSV形式の場合はタブ文字(\t)となります。(※デフォルト値:カンマ(,))

textqualifier

(オプション)ファイルの『囲み文字』を指定。有効な値はシングルクォート('), ダブルクォート(\")。 先頭のバックスラッシュはJSONファイル内でのダブルクォート文字に対して必要なエスケープ文字です。囲み文字が使われていない場合、その項目は値が無い状態となります。(※デフォルト値:ダブルクォート(\"))

containsHeader

(オプション)ファイルがヘッダ行を含むか含まないかを指定。有効値はtrue or false。デフォルト値はtrue。

Amazon QuickSightマニフェストファイルのサンプル

例1:

以下1つ目のサンプルではインポート対象のCSVファイル2つをマニフェストファイルで指定しています。

これらのファイルは囲み文字にダブルクォート(\")を使っています。format,delimiter,containsHeaderフィールドの値に関してはデフォルト値が適用されます。

{ 
    "fileLocations": [                                                    
          {"URIs": [
              "https://data_bucket.s3.amazonaws.com/data.csv",
              "https://data_bucket.s3.amazonaws.com/data2.csv"
           ]}
     ],
     "globalUploadSettings": { 
         "textqualifier": "\""    
    }
}

例2:

2つ目のサンプルがこちら。対象ファイルとなるTSVを2つ指定し、1つはURI指定、もう1つはURIプレフィックス指定で異なるリージョンの任意のバケット全体を指し示しています。textqualifiercontainsHeaderフィールドについてはデフォルト値が適用されます。

{ 
    "fileLocations": [                                                    
          {"URIs": [
               "https://s3.amazonaws.com/data_bucket/data.tsv"
          ]},
          {"URIPrefixes": [
               "https://s3-us-east-1.amazonaws.com/data_bucket/"
          ]}
     ],
     "globalUploadSettings": { 
         "format": "TSV",  
         "delimiter": "\t"         
    }
}

例3:

3つ目のサンプル。URIプレフィックス指定で異なる表現方法でバケット2つを指定しています。対象ファイルはformatにてCLFを指定。 delimiter, textqualifier, containsHeaderについてはログファイル取り込みの為、指定しても無視されます。

{ 
    "fileLocations": [                                                    
          {"URIPrefixes": [
              "https://data_bucket.s3-us-east-1.amazonaws.com",
              "s3://other_data_bucket/"
          ]}
     ],
     "globalUploadSettings": { 
         "format": "CLF" 
    }
}

例4:

4つ目のサンプル。Amazon Redshift形式を使用して、インポートする.csvファイルを識別します。

{
  "entries": [
    {"url":"https://s3-us-west-2.amazonaws.com/carpc-test/Consumer_Complaints3.csv", "mandatory":true}
  ]
}

まとめ

という訳で『Amazon QuickSight Advent Calendar 2016』23本目、『QuickSightでサポートされているファイル取り込み指定方法』に関するご紹介でした。明日もお楽しみに!

参考情報