Web API 関数を使用する

関数は、Web API を使用して実行できる再利用可能な操作です。 Web API には、次の 2 種類の関数があります。

関数: 副作用のない操作を実行するには、GETに記載されている関数と共にWeb API Function Reference要求を使用します。これらの関数は、通常、コレクションまたは複合型のデータを取得します。各関数には、組織サービスに対応するメッセージがあります。
Web API Query Function Referenceに記載されている関数を使用して、クエリの構成内のプロパティと値を評価します。各クエリ関数には、対応する ConditionOperator 値があります。

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

パラメーターを必要とする関数の場合は、パラメーターエイリアスを使用して値を渡すことがベストプラクティスです。

たとえば、 GetTimeZoneCodeByLocalizedName 関数を使用する場合は、 LocalizedStandardName と LocaleId パラメーター値を含める必要があります。次のインライン構文を使用できます。

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

ただし、パラメーターエイリアスを使用してこれらの要求を送信しない限り、要求が失敗する可能性があるいくつかの問題があります。

400 Bad Request - Invalid URLを超えると、エラーが発生する可能性があります
クエリパラメーター #204 としての DateTimeOffset の記事で説明されているように、インライン構文で DateTimeOffset 値を使用する際に問題があります。

次のコードサンプルに示すように、パラメーターエイリアスを使用して値を渡すことで、これらの問題を回避します。

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

パラメーター値を複数回使用する場合、パラメーターエイリアスを使用すると、それを再利用して URL の長さを減らすことができます。

レコード参照を関数に渡す

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

Functions
CalculateRollupField	IncrementKnowledgeArticleViewCount	InitializeFrom
IsValidStateTransition	RetrieveDuplicates	RetrieveLocLabels
RetrievePrincipalAccess	RetrieveRecordWall	ValidateRecurrenceRule

既存のレコードへの参照を渡す場合は、レコードの Uri に @odata.id 注釈を使用します。たとえば、 RetrievePrincipalAccess 関数を使用している場合は、次の URI を使用して、特定の連絡先レコードへのアクセスの取得を指定できます。

GET [Organization URI]/api/data/v9.2/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で見つかった関数、またはカスタム API として作成された関数のみです。クエリ関数はバインドされません。

バインドされた関数

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を表すエンティティ型にバインドされます。この関数は、 RetrieveUserPrivilegesResponse クラスのインスタンスを返す代わりに、 RetrieveUserPrivilegesResponse 複合型を返します。関数が複合型を返す場合、通常、その定義は CSDL 内の関数の定義のすぐ上に表示されます。

バインドされた関数を呼び出すには、関数の完全な名前を 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 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関数はエンティティにバインドされていません。これは、 IsBound 属性なしで CSDL で定義されます。

<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 クラスに対応し、SDK for .NET で使用されるWhoAmIResponse クラスに対応する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 属性があります。これらの各関数には、 ColumnSet または QueryBase 型パラメーターを受け取るコンパニオンメッセージが SDK に含まれています。 OData システムクエリオプションは同じ機能を提供するため、これらの関数には SDK のコンパニオンメッセージと同じパラメーターがありません。次の表に、このリリースの構成可能な関数の一覧を示します。

Functions
RetrieveAllChildUsersSystemUser	RetrieveBusinessHierarchyBusinessUnit	RetrieveUnpublishedMultiple
SearchByBodyKbArticle	SearchByKeywordsKbArticle	SearchByTitleKbArticle

クエリ関数

Web API Query Function Referenceに記載されている関数は、クエリの作成に使用することを目的としています。 OData クエリ関数と同様の方法で使用できますが、いくつかの重要な違いがあります。関数の完全な名前を使用し、パラメーターの名前を含める必要があります。

次の例では、 LastXHours クエリ関数を使用して、過去 12 時間以内に変更されたすべてのアカウントエンティティを返します。

GET [Organization URI]/api/data/v9.2/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.2/systemusers?$select=fullname,systemuserid&$filter=not Microsoft.Dynamics.CRM.EqualUserId(PropertyName=@p1)&@p1='systemuserid'

いくつかのクエリ関数には、否定されたクエリ関数が付属しています。たとえば、 NotEqualUserId は EqualUserIdを否定するため、次のクエリは予想される結果を返します。

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

その他のクエリ関数は、さまざまな方法で否定できます。たとえば、このような Last7Days クエリ関数を否定するのではなく (前述と同じエラーで失敗します)。

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

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

GET [Organization URI]/api/data/v9.2/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 を使用して条件付き操作を実行する

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-04