カスタム 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 で配列データを使用すると エラー が発生する既知の問題があります。

エンティティ クラスを継承して、必要なプロパティを含む 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"
}