こんにちは。CData Software Japan リードエンジニアの杉本です。
今回は最近問い合わせを頂いたCData Dynamics 365 / Dataverse Driver で参照・所有者フィールド（以前は検索フィールドと呼ばれてましたかね）を更新する方法を解説したいと思います。
参照フィールド・所有者フィールド
まず、画面上で参照フィールド・所有者フィールドを確認してみましょう。
標準テーブルの取引先企業（Account）テーブルの場合、以下の取引先責任者が参照フィールド、System adminと書かれている部分が所有者フィールドになりますね。
所有者はDynamics 365 ・Dataverseとしては特殊なフィールドにあたるため、「割り当て」などで対象のユーザーを変更するようになっていたりしますね。
APIで参照フィールド・所有者フィールドを更新する際の問題点
この参照フィールド・所有者フィールドなのですが、ちょっとやっかいな項目になっています。
なぜかと言えば、例えばAPIを通じてこのデータを取得しようとすると以下のように「ownerid_value」や「primarycontactid_value」という項目名で取得されてしまうのです。
Dataverseのカスタマイズ画面を見てみると「OwnerId」や「PrimaryContactId」という名前にも関わらず、こういった形でデータが返却されるのは所有者・参照フィールドの特徴です。
さらに所有者などのデータを更新しようと思って、PATCHやPOSTリクエストで以下のように「_ownerid_value」に値を設定してリクエストしても
PATCH https://XXXXX.crm7.dynamics.com/api/data/v9.0/accounts(b14dd93a-d75b-ec11-8f8f-000d3acf3d96) HTTP/1.1
Host: XXXX.crm7.dynamics.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs
Content-Type: application/json
accept: application/json
{
"@odata.type": "#Microsoft.Dynamics.CRM.account",
"_ownerid_value": "678171e0-295a-ec11-8f8f-00224862886d"
}
「message=CRM do not support direct update of Entity Reference properties, Use Navigation properties instead.」というエラーメッセージが返ってきてしまいます。
対処方法
対処方法はエラーメッセージで返ってきている通りです。
Entiti Referenceプロパティ、つまり参照・所有者フィールドのルールに従って、Navigatinプロパティを使ってアップデートをかけるだけです。
ドキュメントを探すのが難しい気がしますが、以下の部分です。
例えば所有者を変更する場合は「ownerid@odata.bind」というフォーマットで、それに関連付けるエンティティ名とGUIDを「"/systemusers(678171e0-295a-ec11-8f8f-00224862886d)"」で渡す感じになります。
PATCH https://XXXXX.crm7.dynamics.com/api/data/v9.0/accounts(b14dd93a-d75b-ec11-8f8f-000d3acf3d96) HTTP/1.1
Host: XXXXX.crm7.dynamics.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs
Content-Type: application/json
accept: application/json
{
"@odata.type": "#Microsoft.Dynamics.CRM.account",
"ownerid@odata.bind": "/systemusers(678171e0-295a-ec11-8f8f-00224862886d)"
}
これが取引先責任者、Contactsテーブルに対する参照フィールドの場合は以下のようになります。
{ "@odata.type": "#Microsoft.Dynamics.CRM.account", "primarycontactid@odata.bind": "/contacts(9b31859e-8b6f-ec11-8943-000d3a410f95)", }
これでAPIを通じてデータを更新することができます！
CData Driver での利用方法
最後にCData D365 Sales Driver・Dataverse Driverを使って、この参照フィールドの更新を行う方法を紹介します。
CData Driverでも前述のAPI仕様通り、参照・所有者フィールドのGUID値を取得する場合は「ownerid_value」や「 primarycontactid_value」といった項目を利用します。
SELECT _ownerid_value, _primarycontactid_value FROM accounts;
しかしながら、この項目に対してUPDATE文で更新をかけようとしても、前述のAPI仕様と同様にエラーが発生してしまいます。
そこで CData Driverではこれらのナビゲーションプロパティを利用するために「IncludeNavigationProperties」という接続設定をTrueにする必要があります。
これを追加することで項目の一覧に「ownerid」や「primarycontactid」といった項目が追加されます。これがデータの更新用項目です。
あとはこの項目を使って、UPDATE文を実行するだけです。
UPDATE accounts SET primarycontactid = '9b31859e-8b6f-ec11-8943-000d3a410f95', ownerid = '678171e0-295a-ec11-8f8f-00224862886d' WHERE accountid = 'b14dd93a-d75b-ec11-8f8f-000d3acf3d96';
ただし、これらのプロパティはあくまでデータの更新用なので、SELECTでデータを取得しようと思ってもできないので注意してください。
SELECT _ownerid_value, ownerid, _primarycontactid_value,primarycontactid FROM accounts;
おわりに
というわけで、ちょっと特殊な参照・所有者フィールドの対応方法をAPI仕様含めて、お届けしました。
CData Driverを利用するにあたっても、このあたりのAPI仕様のちょっとしたポイントがあるので、もし利用ケースでわからない部分があれば、お気軽にテクニカルサポートまでお問い合わせください。
