カスタム API でオープン型を使用する

[アーティクル]
08/24/2023

カスタム API を使用して Microsoft Dataverse メッセージを作成するには、リクエストパラメータとレスポンスプロパティのそれぞれの名前とデータ型を指定する必要があります。データ型はオープンまたはクローズにすることができます。 クローズド型では、すべてのプロパティと型の値が分かっています。 Dataverse で定義されているすべての型は閉じています。システムは閉じた型を認識しており、それらを検証できます。間違った名前を使用したり、値を間違った型に設定したりすると、エラーが発生します。ただし、閉じた型は動的ではありません。複雑にネストされたプロパティは許可されません。通常、特定の構造は良いことですが、ビジネスロジックではより柔軟なアプローチが必要な場合があります。

密閉型と違い、オープン型は動的プロパティを持つことができます。次の場合には、カスタム API でオープン型を使用するのが合理的です。

構造化された動的データの使用が必要です。このデータはクラスで記述することができないため、シリアル化または逆シリアル化する必要はありません。
カスタム API でリクエストパラメーターを受け入れたり、利用可能なオプションを使い表現できない複合型を持つレスポンスプロパティを返したりします。その場合、カスタム密閉型を使用する必要があります。

オープン型を正しく使用するために、カスタム API に適用されるシナリオを理解することが重要です。まず、オープン型の使用方法を理解しましょう。

オープン型の使用方法

オープン型を使用するには、オープン型用に構成されたメッセージが必要です。カスタム API では、リクエストパラメーターまたはレスポンスプロパティは Type を Entity (3) に、または EntityCollection (4) を LogicalEntityName で指定せずに設定することで開かれます。

LogicalEntityName を指定しない場合、Dataverse にエンティティはテーブル定義に対して検証できないキー/値のペアのコレクションであると示すので、試行されません。 LogicalEntityName を持たない EntityCollection は、単なる エンティティ の配列です。

注意

関数として定義されたカスタム API は、オープン型をリクエストパラメータとして使用できませんが、レスポンスプロパティとして使用することはできます。

Dataverse エンティティの使用

実際にはオープン型ではありませんが、複数のクローズドエンティティ型を表すパラメーターまたはレスポンスプロパティを含むカスタム API を使用できることに注意してください。たとえば、Customer または Account エンティティインスタンスを想定する Contact パラメータを含むカスタム API を作成できます。 Dataverse では、どのような エンティティタイプも可能です。プラグインコードは、Entity.LogicalName 値をチェックして、それが期待するタイプであるかどうかを判断する必要があります。

エンティティを辞書として使用する

より一般的なケースは、エンティティを辞書として使用することです。 Entity.Attributes コレクションを使用して、キーと値のセットを指定します。値は任意の .NET 型にすることができ、ネストすることもできます。他のエンティティクラスのプロパティは使用しないでください。

アプリケーションが Microsoft Graph から送受信されるデータを使用し、educationSchool リソース型を表すとします。次の例のように、オープン型を使用することもできます。

.NET 用 SDK
Web API

SDK でオープン型を使用するには、エンティティ名を指定せずにエンティティクラスを使用し、キーとその値を含む Entity.Attributes コレクションを設定します。

var educationSchool = new Entity() {
    Attributes =
    {
        { "id", Guid.NewGuid() },
        { "displayName","Redmond STEM Academy" },
        { "phone", "555-1234" },
        { "address",  new Entity() //physicalAddress resource type
            {
            Attributes =
                {
                    { "city","Redmond" },
                    { "countryOrRegion","United States" },
                    { "postalCode","98008" },
                    { "state","Washington" },
                    { "street","123 Maple St" },
                }
            }
        }
    }
};

Web API でオープン型を使用するには、@odata.type 注釈値を Microsoft.Dynamics.CRM.expando に設定する必要があります。この注釈では Dataverse に、データはプロパティが無く、crmbaseentity エンティティ型から継承する expando エンティティ型だと示します。 expando エンティティ型について詳しく見る。

{
  "@odata.type": "Microsoft.Dynamics.CRM.expando",
  "id@odata.type": "Guid",
  "id": "59fab58c-46f9-425c-b32d-43726fb6e95b",
  "displayName@odata.type": "String",
  "displayName": "Redmond STEM Academy",
  "phone@odata.type": "String",
  "phone": "555-1234",
  "address": {
    "@odata.type": "Microsoft.Dynamics.CRM.expando",
    "city@odata.type": "String",
    "city": "Redmond",
    "countryOrRegion@odata.type": "String",
    "countryOrRegion": "United States",
    "state@odata.type": "String",
    "state": "Washington",
    "street@odata.type": "String",
    "street": "123 Maple St"
  }
}

id の値には id@odata.type の注釈があることに注目してください。この注釈は、値が String ではなく Guid を表すことを指定するために必要です。指定しない限り、OData は最も単純な JSON 型が意図されていると想定します。

値が数値の場合は、Int32 です。値が Decimal、Double、Int16、Int64 の場合は、<property name>@odata.type の注釈で型を指定する必要があります。

文字列値には、文字列であることを示す注釈が付いていることにも注意してください。これらの注釈は、OData の既知の問題に対する軽減策です。文字列値に開き括弧 ([) または一重引用符 (') が含まれている場合、OData ライブラリは Microsoft.OData.ODataException を返します。送信される値にこれらの文字が含まれないことが確実でない限り、このエラーを防ぐために "<property name>@odata.type": "String" 注釈を含める必要があります。

値が配列の場合は、必ず以下のパターンで注釈を記述する必要があります: "<property name>@odata.type": "Collection(<type>)"

例:

{
  "@odata.type": "Microsoft.Dynamics.CRM.expando",
   "stringArray": ["one","two","three"],
   "stringArray@odata.type": "Collection(String)",
   "intarray": [1,2,3],
   "intarray@odata.type": "Collection(Int32)"
}

Web API で配列データを使用するとエラーが発生する既知の問題があります。

Dataverse タイプを使用する

基本的な .NET の型に加え、Dataverse で知られている型も使用することができます。 .NET 用 SDK には、Dataverse が知る多くのクラスの定義が含まれ、Web API には、これらの型は Web API 複合型の参照と列挙型の参照にリストされています。

SDK を使用する場合は、値を設定するだけで済みます。

Web API を使用する場合は、Web API の名前空間を使用して型を指定する必要があります: Microsoft.Dynamics.CRM。次の例では、これらの Dataverse Web API 型を使用します。

{
  "@odata.type": "Microsoft.Dynamics.CRM.expando",
  "label@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
   "label": {      
      "Label": "Yes",
      "LanguageCode": 1033
   },
  "labelarray": [
    {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "test",
      "LanguageCode": 1033
    },
    {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "prøve",
      "LanguageCode": 1030
    }
  ],
  "labelarray@odata.type": "Collection(Microsoft.Dynamics.CRM.LocalizedLabel)",
  "enumarray": ["DateOnly"],
  "enumarray@odata.type": "Collection(Microsoft.Dynamics.CRM.DateTimeFormat)"
}

構造化された動的データ

構造化された動的データは、JSON、XML、YAML、HTML などの文字列として設定できるさまざまな形式を使用して定義できます。この種のデータは、文字列パラメーターまたは応答プロパティを使用して簡単に設定できます。では、なぜオープン型を使用するのでしょうか？

構造化データがカスタム API を介して別のサービスに渡される場合、またはカスタム API を呼び出す別のアプリケーションによって文字列として消費される場合は、文字列を使用します。
カスタム API をサポートするプラグイン、またはカスタム API を拡張するプラグインが構造化データを読み取りまたは変更する必要がある場合は、オープン型を使用します。

文字列の値を XDocument や JObject などのオブジェクトに解析して、プラグインで操作できるようにするのは、比較的高価な作業です。プラグイン、またはカスタム API のロジックを拡張する可能性のあるその他のプラグインがデータを変更する場合、オブジェクトを文字列に変換し直す必要があります。オープン型を使用すると、これらの負荷の高い操作を回避できます。

オープン型を使用すると、カスタム API の呼び出し元は、エンティティクラスが提供する使い慣れた辞書構造を使用できます。プラグインは、他の Dataverse レコードを操作するのと同じ方法でそのレコードを操作できます。

文字列データをクラスにシリアル化または逆シリアル化している場合、データは動的ではありません。次のセクションを確認してください。

カスタムのクローズド型

オープン型では、動的で非構造化データが可能になります。ただし、API に本当に動的パラメーターがあるかどうか、または実際にカスタム型が必要かどうかを考慮する必要があります。

現在、Dataverse を認識するカスタムタイプを定義することはできません。ただし、オープン型を使用すると、Dataverse オープン型として処理できるクローズド型のクラスを定義できます。カスタム API を使用する開発者は、クラスを使用してエラーの可能性を減らし、より良く更に生産的なエクスペリエンスを得ることができます。

たとえば、カスタム API に緯度と経度の座標の配列を使用してコースを追跡するパラメーターが必要だとします。 Location クラスが必要です。

.NET 用 SDK
Web API

エンティティクラスを継承して、必要なプロパティを含む Location クラスを作成することができます。例:

using Microsoft.Xrm.Sdk;

namespace MyCompany
{
    /// <summary>
    /// Specifies a location for use with my_CustomAPI
    /// </summary>
    public class Location : Entity
    {
        // Gets or sets the latitude of the Location.
        [AttributeLogicalName("Latitude")]
        public double Latitude
        {
            get
            {
                return GetAttributeValue<double>("Latitude");
            }
            set
            {
                SetAttributeValue("Latitude", value);
            }
        }

        // Gets or sets the longitude of the Location.
        [AttributeLogicalName("Longitude")]
        public double Longitude
        {
            get
            {
                return GetAttributeValue<double>("Longitude");
            }
            set
            {
                SetAttributeValue("Longitude", value);
            }
        }
    }
}

この型は Entity クラスを継承しているため、Entity GetAttributeValue と SetAttributeValue メソッドを使用し、Attributes コレクション内の値にアクセスできます。このクラスをプラグインコードで使用し、ライブラリまたはドキュメントのサンプルコードでコンシューマと共有できます。その結果、コードが使いやすく、読みやすくなります。

変更前:

var location = new Entity() { 
   Attributes =
   {
      { "Latitude", 47.66132951804776 },
      { "Longitude", -122.11446844957624},            
   }            
};

// OR 

var location = new Entity();
location["Latitude"] = 47.66132951804776;
location["Longitude"] = -122.11446844957624;

変更後:

var location = new Location { 
   Latitude = 47.66132951804776,
   Longitude = -122.11446844957624
};

// OR 

var location = new Location()
location.Latitude = 47.66132951804776;
location.Longitude = -122.11446844957624;

Web API は .NET や他のプログラミング言語で使用できるため、具体的な方法は JSON 操作に使用する言語とテクノロジによって異なります。

Json.NET を C# で使用する場合、このように Location クラスを定義することができます:

using Newtonsoft.Json;

namespace MyCompany
{
    public class Location 
    {
        [JsonProperty("@odata.type")]
        public string ODataType => "Microsoft.Dynamics.CRM.expando";

        // Gets or sets the latitude of the Location.
        public double? Latitude { get; set; }

        [JsonProperty("Latitude@odata.type")]
        public static string LatitudeType => "Double";

        // Gets or sets the longitude of the Location.
        public double? Longitude { get; set; }

        [JsonProperty("Longitude@odata.type")]
        public static string LongitudeType => "Double";
    }
}

このクラスを、ドキュメントのライブラリまたはサンプルコードのコンシューマと共有できます。

開発者がこのクラスを使用する場合、@odata.type 注釈の設定に悩む必要はありません。

Location location = new() {
   Latitude = 47.66132951804776,
   Longitude = -122.11446844957624
};

// OR 

var location = new()
location.Latitude = 47.66132951804776;
location.Longitude = -122.11446844957624;

@odata.type 注釈は、クラスインスタンスがシリアル化されるときに常に含まれます。

{
    "@odata.type": "Microsoft.Dynamics.CRM.expando",
    "Latitude": 47.66132951804776,
    "Latitude@odata.type": "Double",
    "Longitude": -122.11446844957624,
    "Longitude@odata.type": "Double"
}

既知の問題

Web API で配列データを使用する際のエラー

Web API を使用して配列を含むデータを送信する場合、カスタム API にプラグインがあると次のエラーが発生します。

{
  "error": {
    "code": "0x80040224",
    "message": "Element 'http://schemas.datacontract.org/2004/07/System.Collections.Generic:value' contains 
     data from a type that maps to the name 'System.Collections.Generic:List`1'. The deserializer has no 
     knowledge of any type that maps to this name. Consider changing the implementation of the ResolveName 
     method on your DataContractResolver to return a non-null value for name 'List`1' and namespace 
     'System.Collections.Generic'.",
  }
}

このエラーは、クライアントアプリケーションが .NET 用 SDK を使用している場合、またはカスタム API にプラグインが設定されていない場合には、発生しません。

オープン型に関するご質問は、下部の このページ への フィードバッ ボタンからお寄せください。

参照

カスタム API の作成と使用
 Odata.org 高度なチュートリアル: オープン型

Share via