Analytics Cloud External Data API試してみた

Analytics CloudではSalesforceのオブジェクトだけでなく、CSVを外部データとして取り込むことができます。今回はCSVによるデータ取り込みをExternal Data APIを使って取り込んでみます。External Data APIといっても、やることはロード用のオブジェクトにデータを格納するだけで、あとは勝手にAnalytics Cloud側がデータ取り込みと変換をやってくれます。

参考URLは以下になります。

External Data | Analytics Cloud External Data API Developer's Guide | Salesforce Developers
External Data Metadata Overview | Analytics Cloud External Data Format Reference | Salesforce Developers
Salesforce Analytics Cloud入門（3）～データセット～ - Appirio Japan

認証

ロード用のオブジェクトにデータを格納することが実現できればOKなので、ApexでもSOAP APIでもREST APIでも何でもOKです。SOAPの場合はloginコール、REST APIの場合はOAuth2.0の手段でSessionIDやaccess_tokenを取得してください。今回はREST APIで進めていきます。

InsightsExternalDataの作成

取り込み情報を表すInsightsExternalDataオブジェクトを作成します。

$ curl -i -X POST \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer {access_token}" \
   -d \
'{
  "EdgemartAlias": "Hoge20150926",
  "Action": "None",
  "Operation":"Overwrite",
  "Format":"CSV",
  "MetadataJson": "{base64 encoded MetadataJSON}";
}' \
 'https://{instance_url}/services/data/v34.0/sobjects/InsightsExternalData'

Metadata JSONに関しては後述します。こちらの項目がなくてもデータロード自体は出来ますが、ロードするデータが全て文字列の項目として解釈されてしまいます。上記リクエストをすると、Idが返ってくるので、このIdを後述の処理で利用します。

{
    "id": "06V370000004GT6EAM",
    "success": true,
    "errors": []
}

InsightsExternalDataPartによるデータロード

ロードするデータ部分を表すInsightsExternalDataPartを作成します。

$ curl -i -X POST \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer {access_token}" \
   -d \
'{
  "InsightsExternalDataId": "{InsightsExternalData ObjectID}",
  "DataFile":"{base64 encoded csv body}",
  "PartNumber":1
}' \
 'https://{instance_url}/services/data/v34.0/sobjects/InsightsExternalDataPart'

InsightsExternalDataPart一つあたりのDataFileに格納できる容量は10MBまでなので、10MB以上のデータを取り込む場合は複数のInsightsExternalDataPartを作成する必要があります。その場合、連番としてPartNumberを1から順に増やしていきます。また、DataFileにはgzip形式にも対応しているようです。

{
    "id": "06W370000004M0rEAE",
    "success": true,
    "errors": []
}

取り込み、変換の開始

InsightsExternalDataPartでデータを格納し終わったら取り込み、変換を開始します。InsightsExternalDataのAction項目を”Process”に更新します。

$ curl -i -X PATCH \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer {access_token}" \
   -d \
'{
  "Action": "Process"
}' \
 'https://{instance_url}/services/data/v34.0/sobjects/InsightsExternalData/{InsightsExternalData ObjectID}'

レスポンスのステータスコードとして204が返ってくればOKです。

Analytics Cloudの右上の歯車マークから「データ監視」を選択すると、ロードの状況を確認することができます。最初はキューに入った状態です。

ロードされると状況が「成功」になります。

ロードに失敗すると「警告」「失敗」になります。

MetadataJSONについて

ロードするCSVデータに関するデータ型等のメタデータを定義できます。サンプルは以下のとおり（リファレンスまんまコピペ）。ファイルフォーマットを表す”fileFormat”と、項目の属性を表す”objects”を定義すればOKです。

{
  "fileFormat": {
    "charsetName": "UTF-8",
    "fieldsEnclosedBy": "\"",
    "fieldsDelimitedBy": ",",
    "numberOfLinesToIgnore": 1
  },
  "objects": [
    {
      "connector": "AcmeCSVConnector",
      "description": "",
      "fullyQualifiedName": "SalesData",
      "label": "Sales Data",
      "name": "SalesData",
      "fields": [
        {
          "description": "",
          "fullyQualifiedName": "SalesData.Name",
          "label": "Account Name",
          "name": "Name",
          "isSystemField": false,
          "isUniqueId": false,
          "isMultiValue": false,
          "type": "Text"
        },
        {
          "description": "",
          "fullyQualifiedName": "SalesData.Amount",
          "label": "Opportunity Amount",
          "name": "Amount",
          "isSystemField": false,
          "defaultValue": "0",
          "isUniqueId": false,
          "type": "Numeric",
          "precision": 10,
          "scale": 2,
          "format": "$#,##0.00"
        },
        {
          "description": "",
          "fullyQualifiedName": "SalesData.CloseDate",
          "label": "Opportunity Close Date",
          "name": "CloseDate",
          "isSystemField": false,
          "isUniqueId": false,
          "type": "Date",
          "format": "MM/dd/yyyy",
          "fiscalMonthOffset": 0
        }
      ]
    }
  ]
}

拡張メタデータファイル（XMD）について

拡張メタデータファイル（Extented Metadata＝XMD）はレンズ上の数値のフォーマッティングやラベル名、グラフの色などのグラフの表現方法を決定するファイルになります。こちらは現時点ではAPIで更新できない（と思う）ので、データセットを生成後にWebUIからアップロードする必要があります。

Apexからロードするサンプル

利用用途は無いと思いますが、Apexからはこんな感じで手軽に外部データ取り込みができます。

InsightsExternalData dt = new InsightsExternalData();
dt.Action = 'None';
dt.Operation = 'OverWrite';
dt.Format = 'Csv';
dt.EdgemartAlias = 'Hoge20150927_1';
insert dt;

InsightsExternalDataPart pt = new InsightsExternalDataPart();
pt.InsightsExternalDataId = dt.id;
pt.DataFile = Blob.valueOf('hoge,fuga\naaa,bbb');
pt.PartNumber = 1;
insert pt;

dt.Action = 'Process';
update dt;