Web API 関数の使用

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

関数とアクションは、Web API を使って実行できる再利用可能な操作を表します。 Web API の関数は 2 種類あります。

• 関数
  GET 要求と「Web API Function Reference」に示されている関数を使用して、副作用がない操作を実行します。 一般に、これらの関数は、データを取得します。 コレクションまたは複合型のいずれかを返します。 これらの各関数には、組織サービスに対応するメッセージがあります。

• クエリ関数
  「Web API Query Function Reference」に記載されている関数を使用して、クエリの作成の際にプロパティと値を評価します。 これらの各関数には、対応する ConditionOperator の値があります。

このトピックの内容

関数にパラメーターを渡す

エンティティに対する参照を関数に渡す

バインドされた関数とバインドされていない関数

関数を使用してクエリを作成する

関数にパラメーターを渡す

パラメーターを必要とする関数の場合、パラメーターを使用して値を渡すことをお勧めします。 たとえば、GetTimeZoneCodeByLocalizedName Function を使用する場合、LocalizedStandardName および LocaleId パラメーターの値を含める必要があります。 次に示すようなインライン構文を使用できます。

GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

ただし、インライン構文での DateTimeOffset 値の使用については、次の記事で説明されているように未解決の問題があります。DateTimeOffset as query parameter (クエリ パラメーターとしての DateTimeOffset) #204

したがって、次のコード例に示すように、パラメーターとして値を渡すことお勧めします。 このベスト プラクティスを使用すると、DateTimeOffset に適用される未解決の懸案事項を回避できます。

GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033

また、パラメーター値が複数回使用される場合、URL の合計の長さを短くするために、パラメーター エイリアスを使用してパラメーターの値を再利用できます。

エンティティに対する参照を関数に渡す

特定の関数は既存のエンティティに対する参照を渡す必要があります。 たとえば、次の関数には crmbaseentity EntityType を必要とするパラメーターがあります。

既存のエンティティに対して参照を渡す場合、エンティティの @odata.id コメントを URI に使用します。 たとえば、RetrievePrincipalAccess Function を使用している場合、次の URI を使用して特定の取引先担当者に対するアクセス権の取得を指定できます。

GET cc_WebAPI_ServiceURI/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'} 

@odata.id コメントは完全な URI を指定できますが、相対 URI も指定できます。

バインドされた関数とバインドされていない関数

「Web API Function Reference」に記載されている関数のみをバインドすることができます。 クエリ関数はバインドされることはありません。

バインドされた関数

d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdlでは、Function 要素がバインドされた関数を表す場合、その要素には、true の値を持つ IsBound 属性が指定されています。 関数内に定義された最初の Parameter 要素は、関数がバインドされているエンティティを表します。 パラメーターの Type 属性がコレクションである場合、関数はエンティティのコレクションにバインドされています。 例として、CSDL での CalculateTotalTimeIncident Function と CalculateTotalTimeIncidentResponse ComplexType の定義を次に示します。

<ComplexType Name="CalculateTotalTimeIncidentResponse">
  <Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
  <Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
  <ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>

このバインドされた関数は、組織サービスで使用される CalculateTotalTimeIncidentRequest と同等です。 Web API では、この関数は、CalculateTotalTimeIncidentRequest.IncidentId プロパティを表す incident EntityType にバインドされています。 この関数は、CalculateTotalTimeIncidentResponse を返すのではなく、CalculateTotalTimeIncidentResponse ComplexType を返します。 関数が複合型を返す場合、複合型の定義は、CSDL で関数の定義のすぐ上に表示されます。

バインドされた関数を呼び出すには、関数の完全な名前を URL に追加し、関数名に続くかっこ内に名前付きパラメーターを含めます。 関数の完全名には、名前空間 Microsoft.Dynamics.CRM が含まれています。 バインドされていない関数には、完全な名前を使用しないでください。

次の例は、インシデント エンティティにバインドされた CalculateTotalTimeIncident Functionの使用例を示しています。

• 要求

  GET cc_WebAPI_ServiceURI/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• 応答

  HTTP/1.1 200 OK
  Content-Type: application/json; odata.metadata=minimal
  OData-Version: 4.0
  
  {
    "@odata.context":"cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse","TotalTime":30
  }
  

バインドされていない関数

WhoAmI Functionはエンティティにバインドされていません。 CSDL で IsBound 属性を使用せずに定義されます。

<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>
<Function Name="WhoAmI">
  <ReturnType Type="mscrm.WhoAmIResponse" Nullable="false" />
</Function>

この関数は WhoAmIRequest に対応し、WhoAmIResponse ComplexType (組織サービスで使用される WhoAmIResponse に対応する) を返します。 この関数にパラメーターはありません。

バインドされていない関数を呼び出すときは、次の例のように関数名だけを使用します。

• 要求

  GET cc_WebAPI_ServiceURI/WhoAmI() HTTP/1.1
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• 応答

  HTTP/1.1 200 OK
  Content-Type: application/json; odata.metadata=minimal
  OData-Version: 4.0
  {
   "@odata.context": "cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
   "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1",
   "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1",
   "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1"
  }
  

関数を使用してクエリを作成する

クエリが返すデータを制御するために関数で使用できる 2 つの方法があります。 特定の関数では、関数から返される列や条件をコントロールでき、クエリ関数を使用してクエリ内の条件を評価することができます。

構成可能な関数

Web API Function Reference でリストされた一部の機能は、エンティティのコレクションを返します。 これらの関数のサブセットは、構成可能です。つまり、追加の $select または $filter システム クエリ オプションを含めることで、どの列が結果で返されるかをコントロールできます。 これらの関数には、CSDL の IsComposable 属性があります。 これらの各関数には、ColumnSet または QueryBase のいずれかの型パラメーターを受け取る、組織サービスに対応するメッセージがあります。OData システム クエリ オプションが同じ機能を提供します。そのため、これらの関数には、組織サービスの対応するメッセージと同じパラメーターはありません。 次の表は、このリリースの構成可能な関数の一覧を示します。

クエリ関数

「Web API Query Function Reference」に記載されている関数は、クエリを作成するために使用することを目的にしています。 これらの関数は、標準クエリ機能と同様の方法で使用できますが、いくつかの重要な違いがあります。

関数の完全な名前を使用し、パラメーターの名前を含める必要があります。 次の例は、LastXHours Functionを使用して、過去 12 か月間に変更されたすべての取引先企業エンティティを返す方法を示しています。

GET cc_WebAPI_ServiceURI/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

関連項目

Web API 機能およびアクションのサンプル (C#)
Web API 機能およびアクションのサンプル (クライアント側 JavaScript)
Web API を使用して演算を実行する
HTTP 要求の作成とエラーの処理
Web API を使用したクエリ データ
Web API を使用してエンティティを作成する
Web API を使用してエンティティを取得する
Web API を使用したエンティティの更新と削除
Web API を使用したエンティティの関連付けと関連付け解除
Web API アクションの使用
Web API を使用してバッチ操作を実行する
Web API を使用して別のユーザーを偽装する
Web API を使用する条件付き演算を実行する

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 著作権