CData Software Blog

クラウド連携のCData Software の技術ブログです。

Dynamics 365/CDSに新しく追加された「ファイル」の種類のフィールドをWeb APIから扱う

こんにちは。CData Software Japan リードエンジニアの杉本です。

最近(というわけでもないか。半年前?)Dynamics 365 (Sales/CDS)に新しいフィールドのデータ型「ファイル」形式が追加されました!

データ型の拡張は複数選択オプションセット・イメージ以来ですかね?

docs.microsoft.com

今まで Dynamics 365を使ったことがある方であれば、おそらくわかるかと思いますが

Dynamics 365で「添付ファイル」と言えば、「メモ」もしくは「SharePointドキュメントライブラリ連携」ですね。(Azure Storageを連携するアドオンもありますが、あれは公式ではなかったような)

f:id:sugimomoto:20200502234951p:plain

それが、新しい「ファイル」形式では、以下のようにフィールドを作成すると

f:id:sugimomoto:20200502234957p:plain

このように、なんとも直感的かつわかりやすいフォーマットでフィールドが表示されます!

f:id:sugimomoto:20200502235003p:plain

添付すると、リンク形式になり、そのままファイルをダウンロードできます。いいですね!

メモやSharePointは1レコードに複数ファイル連携できるので、その辺りを勘案しながら使い方を分けるのが良さげです。

f:id:sugimomoto:20200502235010p:plain

API ではどうなってるの?

さて、本題はここからです。この「ファイル」レコード、API上から探ると、実態はどうなっているんでしょうか?

というわけで、Metadata APIから対象のPropertyを見てみました。

Dynamics 365のMetadata APIは「開発者リソース」の以下のリンクから入手できます。(もしくは「https://{tenantid}.api.crm7.dynamics.com/api/data/v9.1/$metadata」)

f:id:sugimomoto:20200502235017p:plain

すると、「ファイル」フィールドは以下の2つの要素で構成されていることがわかりました。

「Type="Edm.Binary"」と「Type="Edm.String"」の2種類のフィールドです。前者はファイルの実態をバイナリで格納し、そのファイル名を後者のフィールドで保持しているようです。

f:id:sugimomoto:20200502235024p:plain

実際にAPIを叩いてみたら、どうなるのかな?

というわけで、単純にエンティティ名でのリクエストをPostmanから実行してみた所、ファイル名を格納しているフィールドしか取得できませんでした。

f:id:sugimomoto:20200502235031p:plain

バイナリファイルはどうやって取得するの?

じゃあ、バイナリはどうやって取得するのかな? と思い調べてみた所、以下のリファレンスに取得方法が掲載されていました。

docs.microsoft.com

以下のようにリクエストを組み立てて、取得します。

GET [Organization URI]/api/data/v9.1/accounts(id)/myfileattribute/$value

私の環境を例にすると、「crfc4_tests」エンティティの「crfc4_files」というフィールドでファイルを管理しています。そのエンティティのGUID「6135b7f3-b58a-ea11-a811-000d3a415f43」レコードからバイナリファイルを取得したいので、最終的なリクエストは以下のようになります。

GET https://sugimomoto36.api.crm7.dynamics.com/api/data/v9.1/crfc4_tests(6135b7f3-b58a-ea11-a811-000d3a415f43)/crfc4_file/$value

Postmanでこれを実行してみると、以下のように文字化けですが、バイナリが取得できました。

f:id:sugimomoto:20200502235038p:plain

Dynamics 365にログイン済みのブラウザでこれを叩いてみると、もっとわかりやすいですね。以下のようにファイルがダウンロードされます。

f:id:sugimomoto:20200502235046p:plain

なお、16MB以上の場合は、チャンクによって分割されてしまうようなので、注意が必要です。

同じようにファイルのアップロード・デリートもできますが、今回は割愛。

以下のソースコードを参照してみてください。

docs.microsoft.com