Web API 関数の使用

注意

エンティティとテーブルの違いがわかりませんか? Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。

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

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

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

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

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

GET [Organization URI]/api/data/v9.0/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)  

ただし、クエリ パラメータ #204 としての DateTimeOffset の記事で説明があるように、インライン構文で DateTimeOffset 値を使用すると問題が発生します。

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

GET [Organization URI]/api/data/v9.0/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033  

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

テーブルへの参照を関数に渡す

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

関数    
CalculateRollupField IncrementKnowledgeArticleViewCount InitializeFrom
IsValidStateTransition RetrieveDuplicates RetrieveLocLabels
RetrievePrincipalAccess RetrieveRecordWall ValidateRecurrenceRule

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

GET [Organization URI]/api/data/v9.0/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」に記載されている関数のみをバインドすることができます。 クエリ関数はバインドされることはありません。

バインドされた関数

CSDL $metadata ドキュメント では、Function 要素がバインドされた関数を表す場合、その要素には、true の値を持つ IsBound 属性が指定されています。 関数内に定義された最初の Parameter 要素は、関数がバインドされているエンティティを表します。 パラメーターの Type 属性がコレクションである場合、関数はエンティティのコレクションにバインドされています。

例として、以下は CSDL の RetrieveUserPrivileges 機能と RetrieveUserPrivilegesResponse 複合型の定義です。

<ComplexType Name="RetrieveUserPrivilegesResponse">
  <Property Name="RolePrivileges" Type="Collection(mscrm.RolePrivilege)" />
</ComplexType
<Function Name="RetrieveUserPrivileges" IsBound="true">
    <Parameter Name="entity" Type="mscrm.systemuser" Nullable="false" />
    <ReturnType Type="mscrm.RetrieveUserPrivilegesResponse" Nullable="false" />
</Function>

このエンティティにバインドされた機能は、組織サービスが使用する RetrieveUserPrivilegesRequest クラスと同等です。 Web API では、この機能は RetrieveUserPrivilegesRequest を意味する systemuser エンティティ タイプにバインドされています。UserId プロパティ。 RetrieveUserPrivilegesResponse クラスのインスタンスを返す代わりに、この関数は RetrieveUserPrivilegesResponse 複合型を返します。 関数が複合型を返す場合、その定義は通常、CSDL の関数の定義のすぐ上に表示されます。

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

重要

バインドされた関数は、最初のパラメーター値を設定するために URI を使って呼び出す必要があります。 名前付きパラメーターの値として設定することはできません。

次の例では、systemuser テーブルにバインドされている RetrieveUserPrivileges 関数を使用している例を表示します。

要求

GET [Organization URI]/api/data/v9.2/systemusers(da455fec-68b7-ec11-9840-000d3a13d713)/Microsoft.Dynamics.CRM.RetrieveUserPrivileges 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": "[Organization URI]/api/data/v8.2/$metadata#Microsoft.Dynamics.CRM.RetrieveUserPrivilegesResponse",
  "RolePrivileges": [
    {
      "Depth": "Global",
      "PrivilegeId": "20db4bf7-60c4-4eb9-ab95-0949766fef1a",
      "BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
      "PrivilegeName": "prvCreateflowsession"
    },
    {
      "Depth": "Global",
      "PrivilegeId": "d8db8e4c-5b76-48eb-b5ec-171b8c661917",
      "BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
      "PrivilegeName": "prvWriteworkflowbinary"
    },
    ... <full list of privileges removed for brevity>
    {
      "Depth": "Global",
      "PrivilegeId": "b234db9f-27a2-4d12-8b51-fc34fbef9d87",
      "BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
      "PrivilegeName": "prvWriteflowsession"
    }
  ]
}
 

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

WhoAmI 関数はエンティティにバインドされていません。 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 クラスに対応する WhoAmIResponse 複合型を返します。 この関数にパラメーターはありません。

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

要求

GET [Organization URI]/api/data/v9.0/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": "[Organization URI]/api/data/v9.0/$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 システム クエリ オプションが同じ機能を提供します。そのため、これらの関数には、組織サービスの対応するメッセージと同じパラメーターはありません。 次のテーブルでは、このリリースの構成可能な関数の一覧が表示されます。

関数    
RetrieveAllChildUsersSystemUser RetrieveBusinessHierarchyBusinessUnit RetrieveUnpublishedMultiple
SearchByBodyKbArticle SearchByKeywordsKbArticle SearchByTitleKbArticle

クエリ関数

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

関数の完全な名前を使用し、パラメーターの名前を含める必要があります。 次の例では、LastXHours クエリ機能を使用して、過去 12 時間で修正されたすべての取引先企業エンティティを返す方法について説明します。

GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12  

クエリ関数の制限

クエリ関数の制限の 1 つは、not 演算子を使ってクエリ関数を否定できない点です。

たとえば、EqualUserId クエリ関数を使用した次のクエリは、次のエラーで失敗します: Not operator along with the Custom Named Condition operators is not allowed

GET [Organization URI]/api/data/v9.1/systemusers?$select=fullname,systemuserid&$filter=not Microsoft.Dynamics.CRM.EqualUserId(PropertyName=@p1)&@p1='systemuserid'

クエリ関数の中には、コンパニオンが拒否したクエリ関数もあります。 たとえば、NotEqualUserId クエリ関数を使用することができます。 次のクエリは、正しい結果を返します。

GET [Organization URI]/api/data/v9.1/systemusers?$select=fullname,systemuserid&$filter=Microsoft.Dynamics.CRM.NotEqualUserId(PropertyName=@p1)&@p1='systemuserid'

他のクエリ関数は、さまざまな方法で拒否することができます。 たとえば、このように (上記で述べたのと同じエラーで失敗します) Last7Days クエリ関数を拒否しようとするより、

GET [Organization URI]/api/data/v9.1/accounts?$select=name&$filter=not Microsoft.Dynamics.CRM.Last7Days(PropertyName=@p1)&@p1='createdon'

次のような OlderThanXDays クエリ関数を使用します。

GET [Organization URI]/api/data/v9.1/accounts?$select=name&$filter=Microsoft.Dynamics.CRM.OlderThanXDays(PropertyName=@p1,PropertyValue=@p2)&@p1='createdon'&@p2=7

参照

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 を使用する条件付き演算を実行する

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。