関数は、Web API を使用して実行できる再利用可能な操作です。 Web API には、次の 2 種類の関数が含まれています。
関数:
GETに記載されている関数と共にWeb API Function Reference要求を使用して、副作用のない操作を実行します。 これらの関数は、通常、コレクションまたは複合型のデータを取得します。 各関数には、組織サービスに対応するメッセージがあります。に記載されている関数を使用して、クエリの構成内のプロパティと値を評価します。 各クエリ関数には、対応する ConditionOperator 値があります。
関数にパラメーターを渡す
パラメーターを必要とする関数の場合は、パラメーターエイリアスを使用して値を渡します。
たとえば、 GetTimeZoneCodeByLocalizedName 関数を使用する場合は、 LocalizedStandardName と LocaleId パラメーター値を含める必要があります。 次のインライン構文を使用できます。
GET/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)
ただし、パラメーターエイリアスを使用してこれらの要求を送信しない限り、いくつかの問題によって要求が失敗する可能性があります。
-
400 Bad Request - Invalid URLを超えると、 エラーが発生します。 - クエリ パラメーター #204 としての DateTimeOffset の記事で説明されているように、インライン構文で DateTimeOffset 値を使用する際に問題があります。
次のコード サンプルに示すように、パラメーターエイリアスを使用して値を渡すことで、これらの問題を回避します。
GET /GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033
パラメーター値を複数回使用する場合、 パラメーターエイリアス を使用すると、それを再利用して URL の長さを減らすことができます。
レコード参照を関数に渡す
特定の関数では、既存のレコードへの参照を渡す必要があります。 たとえば、次の関数には、 crmbaseentity エンティティ型を必要とするパラメーターがあります。
既存のレコードへの参照を渡すときに、レコードの URI に @odata.id 注釈を追加します。 たとえば、 RetrievePrincipalAccess 関数を使用している場合は、次の URI を使用して、特定の連絡先レコードへのアクセスの取得を指定できます。
GET /systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(aaaabbbb-0000-cccc-1111-dddd2222eeee)'}
@odata.id注釈には、完全な URI または相対 URI を指定できます。
バインドされた関数とバインドされていない関数
バインドできるのは、Web API Function Reference として作成した関数だけです。 クエリ関数はバインドされません。
バインドされた関数
CSDL $metadata ドキュメントでは、Function要素がバインドされた関数を表す場合、IsBound値を持つtrue属性があります。 関数で定義されている最初の 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>
このバインドされた関数は、 SDK for .NET RetrieveUserPrivilegesRequest クラスと同じです。 Web API では、この関数はsystemuser を表す エンティティ型にバインドされます。 この関数は 、SDK for .NET RetrieveUserPrivilegesResponse クラスのインスタンスを返す代わりに、 RetrieveUserPrivilegesResponse 複合型を返します。 関数が複合型を返す場合、通常、その定義は CSDL $metadata ドキュメント内の関数の定義のすぐ上に表示されます。
バインドされた関数を呼び出すには、関数の完全な名前を URL に追加し、関数名の後のかっこ内に名前付きパラメーターを含めます。 完全な関数名には、名前空間 Microsoft.Dynamics.CRMが含まれます。 バインドされていない関数では、完全な名前を使用しないでください。
Important
URI を使用してバインドされた関数を呼び出して、最初のパラメーター値を設定します。 名前付きパラメーター値として設定することはできません。
次の例では、RetrieveUserPrivileges テーブルにバインドされているsystemuser関数を使用します。
要求:
GET [Organization URI]/api/data/v9.2/systemusers(da455fec-68b7-ec11-9840-000d3a13d713)/Microsoft.Dynamics.CRM.RetrieveUserPrivileges
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関数はエンティティにバインドされていません。 これは、属性を使用せずに 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>
この関数は、SDK for .NET WhoAmIRequest クラスに対応し、WhoAmIResponseに対応する複合型を返します。 この関数にはパラメーターがありません。
バインドされていない関数を呼び出す場合は、次の例に示すように、関数名のみを使用します。
要求:
GET [Organization URI]/api/data/v9.2/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.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
"BusinessUnitId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
"UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",
"OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}
関数を使用してクエリを作成する
クエリによって返されるデータを制御するには、2 つの方法で関数を使用できます。 特定の関数を使用すると、返される列または条件を制御できます。 クエリ関数を使用して、クエリ内の条件を評価することもできます。
構成可能な関数
Web API Function Referenceにリストされている一部の関数は、エンティティのコレクションを返します。 これらの関数のサブセットは 構成可能です。つまり、 $select または $filter システム クエリ オプションを含め、結果に返される列を制御できます。 これらの関数には、CSDL に IsComposable 属性があります。 これらの各関数には、SDKにはSDK for .NET ColumnSet クラスまたはSDK for .NET QueryBase クラス型パラメーターを受け取る互換メッセージがあります。 OData システム クエリ オプションは同じ機能を提供するため、これらの関数には SDK for .NET のコンパニオン メッセージと同じパラメーターはありません。 次の表に、構成可能な関数の一覧を示します。
クエリ関数
Web API Query Function Referenceに記載されている関数を使用して、クエリを作成します。 OData クエリ関数と同様の方法で使用できますが、いくつかの重要な違いがあります。 関数の完全な名前を使用し、パラメーターの名前を含める必要があります。
次の例では、 LastXHours クエリ関数を使用して、過去 12 時間以内に変更されたすべてのアカウント エンティティを返します。
GET /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 /systemusers?$select=fullname,systemuserid&$filter=not Microsoft.Dynamics.CRM.EqualUserId(PropertyName=@p1)&@p1='systemuserid'
いくつかのクエリ関数には、否定されたクエリ関数が付属しています。 たとえば、 NotEqualUserId は EqualUserIdを否定するため、次のクエリは予想される結果を返します。
GET /systemusers?$select=fullname,systemuserid&$filter=Microsoft.Dynamics.CRM.NotEqualUserId(PropertyName=@p1)&@p1='systemuserid'
その他のクエリ関数は、さまざまな方法で否定できます。 たとえば、このような Last7Days クエリ関数を否定するのではなく (前述と同じエラーで失敗します)。
GET /accounts?$select=name&$filter=not Microsoft.Dynamics.CRM.Last7Days(PropertyName=@p1)&@p1='createdon'
次のように、 OlderThanXDays クエリ関数を使用します。
GET /accounts?$select=name&$filter=Microsoft.Dynamics.CRM.OlderThanXDays(PropertyName=@p1,PropertyValue=@p2)&@p1='createdon'&@p2=7
こちらも参照ください
Web API 関数とアクションのサンプル (C#)
Web API の関数とアクションのサンプル (クライアント側 JavaScript)
Web API の関数とアクションのサンプル (PowerShell)
Web API を使用したデータのクエリ
Web API アクションの使用