Web API 関数の使用

[アーティクル]
08/24/2023

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

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

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

パラメーターを必要とする関数の場合、パラメーターを使用して値を渡すことをお勧めします。

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

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 で見つかった関数、またはカスタム API として作成された関数のみをバインドできます。クエリ関数はバインドされることはありません。

バインドされた関数

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>

このエンティティにバインドされた機能は、.NET 用 SDK が使用する RetrieveUserPrivilegesRequest クラスと同等です。 Web API では、関数は RetrieveUserPrivilegesRequest.UserId プロパティプロパティを表す systemuser エンティティタイプにバインドされています。 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 クラスに対応し、.NET 用 SDK が使用する 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 のいずれかの型パラメーターを受け取る、SDK に対応するメッセージがあります。 OData システムクエリオプションが同じ機能を提供するため、これらの関数には、SDK の対応するメッセージと同じパラメーターはありません。次のテーブルでは、このリリースの構成可能な関数の一覧が表示されます。

関数
RetrieveAllChildUsersSystemUser	RetrieveBusinessHierarchyBusinessUnit	RetrieveUnpublishedMultiple
SearchByBodyKbArticle	SearchByKeywordsKbArticle	SearchByTitleKbArticle

クエリ関数

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

次の例では、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 は EqualUserId を否定するため、次のクエリは期待どおりの結果を返します。

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 分かかります。個人データは収集されません (プライバシーステートメント)。

次の方法で共有