Web API の種類および操作
公開日: 2017年1月
対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online
Web API を使用するには、使用できるものに関する情報を検索する必要があります。 サービスについては、ユーザーがアクセスできるサービスおよびメタデータ ドキュメントで説明されています。 このトピックでは重要な概念を紹介し、サービスおよびメタデータ ドキュメントから生成されたドキュメント、メタデータ ドキュメント、およびシステム エンティティの種類、関数、アクションのドキュメントから必要な情報を検索する方法を説明します。
このトピックの内容
用語
サービス ドキュメント
エンティティの種類
プロパティ
ナビゲーション プロパティ
操作
関数
複合型
列挙の種類
用語
Web API は、精通する必要のある特定の用語を使用する OData v4 標準を使用して実装されます。エンティティ データ モデル (EDM) は OData サービスで公開されるデータを表すのに使用される抽象データ モデルです。 次の表は、OData バージョン 4.0 パート 1: Protocol Plus Errata 02 で定義されている、理解しておく必要のある用語を抽出した一覧です。
用語 |
定義 |
|---|---|
エンティティの種類 |
キーを持つ名前付き構造化の種類です。 名前付きプロパティと、エンティティ間の関連付けを定義します。 エンティティの種類は、他のエンティティの種類の単一の継承から派生する場合があります。 |
エンティティ |
エンティティの種類のインスタンス (たとえば、account、opportunity)。 |
エンティティ セット |
エンティティの名前付きコレクション (たとえば、accounts は account エンティティを含むエンティティ セット)。 エンティティ キーはエンティティ セット内のエンティティを一意に識別します |
複合型 |
プロパティ セットで構成される、キーを持たない名前付き構造化の種類です。 複合型は、一般的にモデル エンティティのプロパティの値や、パラメーター、操作の戻り値として使用されます。 |
列挙の種類または Enum の種類 |
整数を基盤とする名前付き定数の値を持つ名前付きプリミティブの種類です。 |
関数 |
追加のフィルター操作、関数またはアクションなど、さらなるコンポジションをサポートする場合のある、副作用のない操作です |
操作 |
データ変更などの副作用を許容し、非決定論的な動作を回避するよう構成できない操作です |
サービス ドキュメント
Web API の詳細については、2 つのサービス ドキュメントを参照してください。
サービス ドキュメント
ブラウザのアドレス フィールドに入力されている次のクエリは、組織で利用できるすべてのエンティティ セットの完全なリストである サービス ドキュメント を返します。[組織 URI] は、組織の URL を表すことに留意してください。
[組織 URI]/api/data/v8.2
エンティティ セットは JSON 配列の形式で返されます。 配列の各項目には、表に示すように、3 つのプロパティがあります。
プロパティ |
説明 |
|---|---|
name |
エンティティ セットの名前です。 このデータは、エンティティの EntityMetadata EntityTypeEntitySetName プロパティからのデータです。 |
kind |
Web API にはエンティティ セットのみ表示されています。 |
url |
この値は name プロパティと共通で、エンティティにデータを取得するためのリソース パスの一部を表します。 |
この情報は、GET 要求を使用して取得することができ、使用できるエンティティ セットの一覧をサービスを使用して入手すると役に立つことがあります。
CSDL メタデータ ドキュメント
次の URL に対する GET 要求は、比較的大きな (3.5 MB 以上) Common Schema Definition Language (CSDL) ドキュメント、またはサービスによって公開されるデータおよび操作を示す メタデータ ドキュメント を返します。
[組織 URI]/api/data/v8.2/$metadata
このドキュメントは、サービスに厳密に型指定したオブジェクトを提供するクラスを生成するためのデータ ソースとして使用できます。 生成されたクラスを使用しない場合、代わりにこの情報から生成されたドキュメントを確認する必要がある場合があります。Web API Reference は、カスタマイズされていないシステムから取得したこのドキュメントの情報を主に使用します。
このドキュメントに関する詳細については、OData バージョン 4.0 パート 3: Common Schema Definition Language (CSDL) Plus Errata 02 を参照してください。
ヒント
このトピックを読み進める前に、組織で使用する CSDL をダウンロードし、説明されている種類、関数、アクションが CSDL やサポート ドキュメントにどのように含まれているかを確認してください。
エンティティの種類
Web API EntityType Reference は、ビジネス データを格納している Web API を通して公開されるシステム エンティティの種類の一覧です。 エンティティの種類は、キーを持つ名前付き構造化の種類です。 名前付きプロパティと、エンティティ間の関連付けを定義します。 エンティティの種類は、他のエンティティの種類の単一の継承から派生する場合があります。Web API Metadata EntityType Reference は、システム メタデータの管理に使用されるエンティティの種類の一覧です。 どちらもエンティティの種類ですが、その使用方法は異なります。 モデル エンティティの使用に関する詳細については、Web API を Dynamics 365 メタデータで使用する を参照してください。 各エンティティの種類には、CSDL 内の EntityType 要素が含まれています。 次は、プロパティおよびナビゲーション プロパティが削除された CSDL からの account EntityType の定義です。
<EntityType Name="account" BaseType="mscrm.crmbaseentity">
<Key>
<PropertyRef Name="accountid" />
</Key>
<!--Properties and navigation properties removed for brevity-->
<Annotation Term="Org.OData.Core.V1.Description" String="Business that represents a customer or potential customer. The company that is billed in business transactions." />
</EntityType>
SDK ドキュメントの各 EntityType 参照ページでは、使用できる場合、次の情報の表示に CSDL またはメタデータの情報を使用します。
情報 |
説明 |
|---|---|
説明 |
エンティティの説明です。 EntityMetadata EntityTypeDescription プロパティ情報は、Term 属性の値が Org.OData.Core.V1.Description である Annotation 要素を使用する EntityType 要素に含まれています。 |
集荷 URL |
各種類のコレクションにアクセスするための URL です。 EntityMetadata EntityTypeEntitySetName プロパティ情報は、CSDL EntityContainer 要素を使用して含まれます。 各 EntitySet 要素の Name 属性は、URL からデータがどのようにアクセスされるかを管理します。 |
ベースの種類 |
これがエンティティの種類が継承するエンティティの種類です。 EntityType 要素の BaseType 属性は、エンティティの種類の名前を含みます。 名前には、Microsoft.Dynamics.CRM 名前空間のエイリアスである mscrm が接頭辞として付加されます。詳細:種類の継承 |
[表示名] |
この情報は CSDL に含まれておらず、EntityMetadata EntityTypeDisplayName プロパティから取得されます。 |
主キー |
エンティティのインスタンスを参照する一意の識別子を含む、属性の値です。 EntityMetadata EntityTypePrimaryIdAttribute プロパティの値は、EntityTypeKey 要素に含まれます。 各エンティティには、主キーを 1 つだけ設定できます。 代替キーは表示されていません。詳細:代替キー |
主属性 |
多くのエンティティは主属性の値の設定を必要とするので、便宜上含まれています。 この情報は CSDL に含まれておらず、メタデータ EntityMetadata EntityTypePrimaryNameAttribute プロパティから取得されます。 |
プロパティ |
「プロパティ」を参照してください。 |
単一値ナビゲーション プロパティ |
「単一値ナビゲーション プロパティ」を参照してください。 |
コレクション値ナビゲーション プロパティ |
「コレクション値ナビゲーション プロパティ」を参照してください。 |
エンティティの種類にバインドされた操作 |
操作が特定のエンティティの種類にバインドされている場合、便宜上表示されます。 |
エンティティの種類を使用する操作 |
この一覧では、エンティティの種類を使用する場合がある操作を示します。 これは、パラメーター内の現在の種類を参照するすべての操作対する参照を収集することで、または戻り値として取得されます。 |
エンティティの種類から継承するエンティティの種類 |
この一覧では、エンティティの種類から直接継承する任意のエンティティの種類を示します。 詳細については、「種類の継承」を参照してください。 |
エンティティ セット名の変更
既定では、エンティティ セット名は EntityMetadata EntityTypeLogicalCollectionName (EntityMetadataLogicalCollectionName) プロパティの値と一致します。 異なるエンティティ セット名を使用して対応したいユーザー定義エンティティがある場合、異なる名前を使用するように EntityMetadata EntityTypeEntitySetName (EntityMetadataEntitySetName) プロパティの値を更新できます。
代替キー
Microsoft Dynamics 365 では代替キーを作成できますが、Microsoft Dynamics 365 SDK ドキュメントには主キーのみ表示されます。
システム エンティティには代替キーは定義されていません。 エンティティに代替キーを定義すると、CSDL EntityType 要素に次のような Annotation として含まれます。
<Annotation Term="OData.Community.Keys.V1.AlternateKeys">
<Collection>
<Record Type="OData.Community.Keys.V1.AlternateKey">
<PropertyValue Property="Key">
<Collection>
<Record Type="OData.Community.Keys.V1.PropertyRef">
<PropertyValue Property="Alias" String="key name" />
<PropertyValue Property="Name" PropertyPath="key name" />
</Record>
</Collection>
</PropertyValue>
</Record>
</Collection>
</Annotation>
代替キーに関する情報は Web API を使用する EntityMetadata EntityTypeKeys コレクション値ナビゲーション プロパティを使用するメタデータまたは、組織のサービスを使用する EntityMetadataKeys プロパティから取得できます。
種類の継承
継承は、一般的なプロパティの共有と、エンティティの種類をグループに分類することを可能にします。 Web API 内のすべてのエンティティの種類は、次の 2 つのエンティティの種類から継承します。 すべてのビジネス エンティティの種類は crmbaseentity EntityType から継承し、すべてのモデル エンティティは crmmodelbaseentity EntityType から継承します。
ベース エンティティ |
説明 |
|---|---|
すべてのビジネス エンティティはのこのエンティティから継承します。 プロパティはありません。 抽象ベース エンティティとしての役割のみを果たします。 |
|
すべての活動エンティティはのこのエンティティから継承します。 活動エンティティに、一般的なプロパティのセットおよびナビゲーション プロパティを定義します。 |
|
systemuser EntityType および team EntityType は、このエンティティから一般的な ownerid プロパティを継承します。 |
|
MetadataBase EntityType のみ、このエンティティから直接継承します。 プロパティはありません。 抽象ベース エンティティとしての役割のみを果たします。 |
|
すべてのモデル エンティティはのこのエンティティから継承します。 これは、すべてのモデル エンティティに HasChanged および MetadataId プロパティを提供します。 |
|
異なる種類の属性を表すすべてのモデル エンティティは、このエンティティから継承します。 |
|
一連のオプションを含む属性を表すモデル エンティティは、このエンティティから継承します。 |
|
このモデル エンティティの種類は、それから継承する BooleanOptionSetMetadata EntityType および OptionSetMetadata EntityType モデル エンティティの種類が使用する一般的なプロパティのセットを提供します。 |
|
このモデル エンティティの種類は、それから継承する ManyToManyRelationshipMetadata EntityType および OneToManyRelationshipMetadata EntityType モデル エンティティの種類が使用する一般的なプロパティのセットを提供します。 |
プロパティ
各エンティティの種類には、属性に対応する宣言済プロパティがある場合があります。Web API EntityType Reference および Web API Metadata EntityType Reference の内容では、ベース エンティティの種類から継承されたプロパティは、各エンティティの種類の宣言済プロパティの一覧にまとまられています。 継承は、各プロパティの説明で実行されます。
CSDL EntityType 要素では、各プロパティが、コードで設定するプロパティに対応する Name 属性を持つ Property 要素に含まれます。Type 属性の値は、プロパティのデータの種類を指定します。 ビジネス エンティティの種類のプロパティは、一般的に OData プリミティブの種類を使用します。
CSDL での account EntityTypename プロパティの定義の例を次に示します。
<Property Name="name" Type="Edm.String" Unicode="false">
<Annotation Term="Org.OData.Core.V1.Description" String="Type the company or business name." />
</Property>
プロパティの説明は、Org.OData.Core.V1.Description の Term 属性のプロパティを持つ Annotation 要素で使用できます。 この説明は、AttributeMetadata EntityTypeDescription 属性の値から取得されます。 説明を持たないプロパティもあります。
各プロパティは計算される場合があります。 これにより、システムによって値が設定される場合があります。 これは、Org.OData.Core.V1.Computed の Term 属性の値を持つAnnotation 要素内で指定されています。
各プロパティには、更新できるかどうかの制限がある場合もあります。 これは、Org.OData.Core.V1.Permissions の Term 属性の値を持つAnnotation 要素内で定義されています。 これの唯一のオプション セットは Org.OData.Core.V1.PermissionType/Read であり、プロパティが読み取り専用であることを示します。
プリミティブの種類
OData はさまざまなデータの種類をサポートしますが、Microsoft Dynamics 365 はそのすべては使用しません。 次の表は、Dynamics 365 組織のサービスの種類がどのように OData プリミティブの種類にマップされているかを示します。
組織のサービスの種類 |
Web API の種類 |
説明 |
|---|---|---|
BigInt |
Edm.Int64 |
署名済 64 ビット整数 |
Boolean |
Edm.Boolean |
バイナリ値ロジック |
CalendarRules |
単一値ナビゲーション プロパティ |
calendarrule EntityType の特定の単一値ナビゲーション プロパティです。 |
顧客 |
単一値ナビゲーション プロパティ |
この種類のプロパティを持つ顧客は、それぞれに設定された単一値ナビゲーション プロパティを使用する account または contact 要素の種類に設定された単一値ナビゲーション プロパティである場合があります。 それぞれの単一値コレクション プロパティのどちらかが設定されると、他方が消去されます。 |
DateTime |
Edm.DateTimeOffset |
うるう秒のない、タイム ゾーンのオフセットを持つ日付と時刻 |
[小数] |
Edm.Decimal |
固定された小数以下の精度およびスケールを持つ数値 |
Double |
Edm.Double |
IEEE 754 binary64 浮動小数点数 (小数点以下 15～17 桁) |
EntityName |
Edm.String |
UTF-8 文字のシーケンス |
画像 |
Edm.Binary |
バイナリ データ |
整数 |
Edm.Int32 |
署名済 32 ビット整数 |
ルックアップ |
単一値ナビゲーション プロパティ |
特定のエンティティに対する参照 |
ManagedProperty |
適用なし |
内部のみで使用 |
メモ |
Edm.String |
UTF-8 文字のシーケンス |
金額 |
Edm.Decimal |
固定された小数以下の精度およびスケールを持つ数値 |
所有者 |
単一値ナビゲーション プロパティ |
principal EntityType への参照です。systemuser および team エンティティの種類の両方は、ownerid プロパティを prinicipal エンティティの種類から継承します。 |
関係者リスト |
activityparty エンティティの種類のコレクション値ナビゲーション プロパティです。 |
activitypartyparticipationtypemask プロパティには関係者のロールを表す値が含まれます。 詳細については、「活動関係者の種類」を参照してください。 |
Picklist |
Edm.Int32 |
署名済 32 ビット整数 |
都道府県 |
Edm.Int32 |
署名済 32 ビット整数 |
Status |
Edm.Int32 |
署名済 32 ビット整数 |
文字列 |
Edm.String |
UTF-8 文字のシーケンス |
Uniqueidentifier |
Edm.Guid |
16 バイト (128 ビット) の一意の識別子 |
検索プロパティ
ほとんどの単一値ナビゲーション プロパティには、命名規則として _<name>_value を使用する計算された読み取り専用のプロパティがあり、<name> は単一値ナビゲーション プロパティの名前と一致します。 このパターンの例外として、エンティティ内の検索属性に複数の種類のエンティティ参照を指定できる場合があります。 一般的な例えとして、incident 要素の customerid 属性が contact または account である参照として設定されている場合です。incident EntityTypeSingle-valued navigation properties では、customerid_account および customerid_contact は、営業案件に関連付けられた顧客を反映する個別の単一値ナビゲーション プロパティです。 両方 customerid にバインドされているため、これら単一値ナビゲーション プロパティの 1 つを設定すると、他方が null に設定されます。incident EntityTypeProperties では、どちらかの単一値ナビゲーション プロパティに設定されている値と同じ値が含まれる _customerid_value 検索プロパティに値が含まれています。
通常、検索プロパティの使用はできるだけ避け、対応する単一値ナビゲーション プロパティを使用します。 これらのプロパティは、一部の統合シナリオに役立つ場合があるために含まれています。 これらのプロパティは、適用された変更を対応する単一値ナビゲーション プロパティを使用して反映するのみのため、読み取り専用および計算されたプロパティです。
クエリに検索プロパティを含めると、単一値ナビゲーション プロパティで表されない基盤とする属性に設定されているデータの追加情報を提供する注釈を含めるよう要求できます。詳細:検索プロパティに関するデータの取得
ナビゲーション プロパティ
OData では、ナビゲーション プロパティを使用すると、現在のエンティティと関連付けられたデータにアクセスすることができます。 エンティティの取得時に、関連データを含めるためにナビゲーション プロパティを拡張することができます。 ナビゲーション プロパティには、単一値とコレクション値の 2 種類があります。
単一値ナビゲーション プロパティ
これらプロパティは、多対一関係をサポートし、別のエンティティに対する参照が設定できるような検索属性に対応します。 CSDL EntityType 要素では、これらは Type が単一の種類に設定されている NavigationProperty 要素として定義されます。 CSDL の account EntityType createdby 単一値のナビゲーション プロパティの例を次に示します。
<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby">
<ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" />
</NavigationProperty>
単一値のナビゲーション プロパティを表すすべてのナビゲーション プロパティは、Partner 属性の値によって示された、対応するコレクション値ナビゲーション プロパティを持ちます。 個々の単一値のナビゲーション プロパティは、関連する要素の GUID 値の取得に使用できる、計算された読み取り専用の検索プロパティを表す Property 属性の値を持つ ReferentialConstraint 要素を持ちます。詳細:検索プロパティ
コレクション値ナビゲーション プロパティ
これらのプロパティは一対多または多対多の関連付けに対応します。 CSDL EntityType 要素では、これらは Type が種類のコレクションに設定されている NavigationProperty 要素として定義されます。 次に示すものは、account EntityTypeAccount_Tasks 一対多の関連付けを表すコレクション値ナビゲーション プロパティを示します。
<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />
コレクション値ナビゲーション プロパティが多対多の関連付けを表す場合は、ナビゲーション プロパティの名前とパートナーの名前は同じです。 次に示すものは、account EntityTypeaccountleads_association 多対多の関連付けを表すコレクション値ナビゲーション プロパティを示します。
<NavigationProperty Name="accountleads_association" Type="Collection(mscrm.lead)" Partner="accountleads_association" />
Web API の使用時は、一対多と多対多の関連付けの違いは重要ではありません。 エンティティの関連付け方法は、関連付けの種類に関係なく同じです。 多対多の関連付けは裏で交差エンティティを使用しますが、Web API EntityType Reference にはいくつかの特別なシステムの交差エンティティしか含まれていません。 たとえば、campaignactivityitem EntityType は正確には交差エンティティですが、通常の交差エンティティよりも多くのプロパティを持つため含まれています。
通常の交差エンティティは、多対多の関連付けを維持するために必要な 4 つの基本プロパティのみを持ちます。 エンティティ間にユーザー定義の多対多関連付けを作成すると、関連付けをサポートするために通常の交差エンティティが作成されます。 多対多の関連付け関係する操作を実行するのにナビゲーション プロパティを使用する必要があるため、通常の交差エンティティはドキュメントに記載されていませんが、Web API で使用できます。 これら交差エンティティは、命名規則に <交差エンティティの論理名> + ’コレクション’ を使用するエンティティ セット名を使用してアクセスできます。 たとえば、[組織 URI]/api/data/v8.2/contactleadscollection を使用して contactleads 交差エンティティの種類から情報を取得できます。 これら通常の交差エンティティは、変更の追跡を適用したい場合にのみ使用します。
操作
アクションは、データ変更などの副作用を許容し、非決定論的な動作を回避するよう構成できない操作です。
この Web API Action Reference トピックでは、使用できる各システム アクションが一覧表示されます。詳細:Web API アクションの使用。
関数
関数 は、追加のフィルター操作、関数、アクションなど、さらなるコンポジションをサポートする場合のある、副作用のない操作です。
Web API では関数が 2 種類定義されています。
この Web API Function Reference トピックでは、使用できる各システム関数が一覧表示されます。
Web API Query Function Reference トピックでは、クエリの条件として使用することを目的とした関数が一覧表示されます。
複合型
複合型は、プロパティ セットで構成される、キーを持たない名前付き構造化の種類です。 複合型は、一般的にモデル エンティティのプロパティの値や、パラメーター、操作の戻り値として使用されます。
Web API ComplexType Reference は、すべてのシステム複合型を一覧表示します。複合型は、プロパティ セットで構成される、キーを持たない名前付き構造化の種類です。 これらは、一般的にモデル エンティティのプロパティの値や、パラメーター、操作の戻り値として使用されます。 次は、CSDL からの WhoAmIResponse ComplexType です。
<ComplexType Name="WhoAmIResponse">
<Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
<Property Name="UserId" Type="Edm.Guid" Nullable="false" />
<Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
列挙の種類
列挙の種類 または EnumTypes は、整数を基盤とする名前付き定数の値を持つ名前付きプリミティブの種類です。
Web API EnumType Reference は、すべてのシステム列挙の種類を一覧表示します。列挙の種類 は、整数を基盤とする名前付き定数の値を持つ名前付きプリミティブの種類です。 次は、CSDL からの AccessRights EnumType です。
<EnumType Name="AccessRights">
<Member Name="None" Value="0" />
<Member Name="ReadAccess" Value="1" />
<Member Name="WriteAccess" Value="2" />
<Member Name="AppendAccess" Value="4" />
<Member Name="AppendToAccess" Value="16" />
<Member Name="CreateAccess" Value="32" />
<Member Name="DeleteAccess" Value="65536" />
<Member Name="ShareAccess" Value="262144" />
<Member Name="AssignAccess" Value="524288" />
</EnumType>
関連項目
Microsoft Dynamics 365 Web API の使用
Web API を使用して Microsoft Dynamics 365 への認証
Web API を使用して演算を実行する
Microsoft Dynamics 365
© 2017 Microsoft. All rights reserved. 著作権