Web API アクションの使用

[アーティクル]
07/22/2023

アクションと関数は、Web API を使って実行できる再利用可能な操作を表します。 POST 要求と「Web API Action Reference」に示されているアクションを使用して、副作用がある操作を実行します。カスタムアクションを定義することもできます。詳細: 独自のメッセージの作成。

アクションは CSDL $metadata ドキュメントで定義されています。 Web API アクションを参照してください。

バインドされていないアクション

以下の XML は、$metadata サービスドキュメントに示されている Merge アクションの定義です。

<Action Name="Merge">
   <Parameter Name="Target" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="Subordinate" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="UpdateContent" 
      Type="mscrm.crmbaseentity" />
   <Parameter Name="PerformParentingChecks" 
      Type="Edm.Boolean" 
      Nullable="false" />
</Action>

Merge アクションは、.NET 用 SDK を使用している MergeRequest に対応します。このアクションを使用して、重複するレコードのペアをマージします。このアクションに戻り値はありません。成功すると、操作が完了します。

次の例は、2 つの取引先企業レコードの Merge アクションを呼び出す HTTP 要求と応答です。

要求:

POST [Organization URI]/api/data/v9.2/Merge HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
  "Target": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "cc1e2c4a-e577-ec11-8d21-000d3a554dcd"
  },
  "Subordinate": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "e408fa45-3a70-ec11-8943-00224823561e"
  },
  "PerformParentingChecks": false
}

応答:

HTTP/1.1 204 No Content
OData-Version: 4.0

詳細: Web API を使用してテーブル行をマージする

バインドされたアクション

アクションをバインドする方法は 2 つあります。最も一般的な方法は、アクションをエンティティにバインドすることです。それほど頻繁ではありませんが、エンティティコレクションにバインドすることもできます。

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

バインドされた関数を呼び出すときは、Microsoft.Dynamics.CRM 名前空間を含めた関数の完全な名前を使用する必要があります。完全な名前を使用しないと、次のエラーが発生します。Status Code:400 Request message has unresolved parameters。

テーブルにバインドされたアクション

エンティティにバインドされたアクションの例として、以下は CSDL で説明されている AddToQueue アクションです。

 <ComplexType Name="AddToQueueResponse">
     <Property Name="QueueItemId" 
        Type="Edm.Guid" 
        Nullable="false" />
 </ComplexType>
 <Action Name="AddToQueue" 
    IsBound="true">
  <Parameter Name="entity" 
    Type="mscrm.queue" 
    Nullable="false" />
  <Parameter Name="Target" 
    Type="mscrm.crmbaseentity" 
    Nullable="false" />
  <Parameter Name="SourceQueue" 
    Type="mscrm.queue" />
  <Parameter Name="QueueItemProperties" 
    Type="mscrm.queueitem" />
  <ReturnType Type="mscrm.AddToQueueResponse" 
    Nullable="false" />
</Action>

このエンティティにバインドされたアクションは、.NET 用 SDK が使用する AddToQueueRequest と同等です。 Web API では、このアクションは AddToQueueRequest を意味する queue エンティティタイプにバインドされています。DestinationQueueId プロパティの値を指定することができます。このアクションは、さらにいくつかのパラメーターを受け入れ、.NET 用 SDK で返した AddToQueueResponse に対応する AddToQueueResponse の複合型を返します。アクションが複合型を返す場合、複合型の定義は、CSDL でアクションのすぐ上に表示されます。

エンティティにバインドされたアクションは、最初のパラメーター値を設定するために URI を使用して呼び出されます。名前付きパラメーターの値として設定することはできません。

次の例は、キューに文字を追加する AddToQueue アクションの使用についてです。 Target パラメーターの種類が固有 (mscrm.crmbaseentity) ではないため、オブジェクトの種類を明示的に宣言する必要があります。この宣言には、@odata.type プロパティの値として、Microsoft.Dynamics.CRM 名前空間を含むエンティティの完全名を使用します。この例の場合は、Microsoft.Dynamics.CRM.letter になります。詳細:エンティティのパラメータの種類を指定する

要求:

POST [Organization URI]/api/data/v9.2/queues(56ae8258-4878-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "Target": {
  "activityid": "59ae8258-4878-e511-80d4-00155d2a68d1",
  "@odata.type": "Microsoft.Dynamics.CRM.letter"
 }
}

応答:


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.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

テーブルコレクションにバインドされたアクション

エンティティコレクションにバインドされたアクションを見つけることはあまり一般的ではありません。次のようなものがある可能性があります。

Dynamics 365 for Sales の FulfillSalesOrder

CreateMultiple

UpdateMultiple

エンティティコレクションにバインドされたアクションの例として、以下は CSDL $metadata で説明されている ExportTranslation アクションです。

<ComplexType Name="ExportTranslationResponse">
   <Property Name="ExportTranslationFile" 
    Type="Edm.Binary" />
</ComplexType>
<Action Name="ExportTranslation" 
    IsBound="true">
   <Parameter Name="entityset" 
    Type="Collection(mscrm.solution)" 
    Nullable="false" />
   <Parameter Name="SolutionName" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
   <ReturnType Type="mscrm.ExportTranslationResponse" 
    Nullable="false" />
</Action>

このエンティティコレクションにバインドされたアクションは、.NET 用 SDK が使用する ExportTranslationRequest と同等です。 Web API では、このアクションは solution エンティティタイプにバインドされています。ただし、要求に値を渡すのではなく、エンティティコレクションバインドは、要求の URI に指定されたエンティティセットへのパスを含める必要があるという制約を適用するだけです。

次の例は、バイナリファイルをエクスポートする ExportTranslation アクションの使用についてです。このバイナリファイルには、変更またはローカライズが可能な値に追加できる、ローカライズ可能な文字列の値に関するデータが含まれます。エンティティコレクションにバインドされたアクションが、ソリューションエンティティ solutions のエンティティセット名の後にどうなっているかに注目してください。

要求:

POST [Organization URI]/api/data/v9.2/solutions/Microsoft.Dynamics.CRM.ExportTranslation HTTP/1.1
Accept: application/json
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "SolutionName":"MySolution"
}

応答:

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.ExportTranslationResponse",
    "ExportTranslationFile": "[Binary data Removed for brevity]"
}

カスタムアクションの使用

カスタムアクションは、カスタム API またはカスタムプロセスアクションです。どちらの方法で作成しても、対応する操作を使用できます。カスタム API を使用する場合、操作は関数です。詳細: 独自のメッセージの作成

以下の例はカスタムプロセスアクション用です。

カスタムアクションの例: 取引先担当者にメモを追加

特定の取引先担当者に新しいメモを追加するカスタムアクションを作成することを考えてみましょう。次のプロパティを持つ取引先担当者エンティティにバインドされているカスタムアクションを作成できます。

UI ラベル	値
プロセス名	AddNoteToContact
一意の名前	new_AddNoteToContact
エンティティ	取引先担当者
カテゴリ	アクション

プロセスの引数

名前	種類	必須項目	方向
NoteTitle	文字列	必須項目	Input
NoteText	文字列	必須項目	Input
NoteReference	エンティティ参照	必須項目	Output

ステップ

名前	ステップの種類	説明
メモの作成	[レコードの作成]	Title = {NoteTitle(Arguments)} Note Body = {NoteText(Arguments)} Regarding = {Contact{Contact}}
メモへの参照を返す	値の割り当て	NoteReference Value = {Note(Create the note (Note))}

カスタムアクションを公開してアクティブ化した後、CSDL をダウンロードするときに、この新しいアクションが定義されていることがわかります。


<Action Name="new_AddNoteToContact" 
    IsBound="true">
  <Parameter Name="entity" 
    Type="mscrm.contact" 
    Nullable="false" />
  <Parameter Name="NoteTitle" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
  <Parameter Name="NoteText" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
  <ReturnType Type="mscrm.annotation" 
    Nullable="false" />
</Action>

次の HTTP 要求と応答は、カスタムアクションを呼び出す方法と、成功した場合に返される応答を示しています。

要求:

POST [Organization URI]/api/data/v9.2/contacts(94d8c461-a27a-e511-80d2-00155d2a68d2)/Microsoft.Dynamics.CRM.new_AddNoteToContact HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "NoteTitle": "New Note Title",
 "NoteText": "This is the text of the note"
}

応答:


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#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

テーブルタイプパラメーターを指定する

操作がパラメータとしてのエンティティを必要し、エンティティの種類が曖昧である場合は、@odata.type プロパティを使用して、エンティティの種類を指定する必要があります。このプロパティの値は、エンティティの完全修飾名であり、このパターンに従います: Microsoft.Dynamics.CRM.+<entity logical name>。

上記のバインドされたアクションセクションにあるように、AddToQueue アクションへの Target のパラメータはアクティビティです。しかし、すべてのアクティビティは activitypointer エンティティのタイプから継承されているため、エンティティのタイプが文字であることを指定するには、エンティティ JSON に次のプロパティを含めてエンティティのタイプが文字であることを指定する必要があります: "@odata.type": "Microsoft.Dynamics.CRM.letter"。

Members パラメーターは、principal エンティティタイプから ownerid 主キーを継承する systemuser エンティティタイプのコレクションであるため、他の 2 つの例は AddMembersTeam と RemoveMembersTeam アクションです。コレクション内の単一のシステムユーザーを表すために次の JSON を渡して場合、エンティティがシステムユーザーであり、teamエンティティタイプ。これもプリンシパルエンティティタイプから継承します。

{
 "Members": [{
  "@odata.type": "Microsoft.Dynamics.CRM.systemuser",
  "ownerid": "5dbf5efc-4507-e611-80de-5065f38a7b01"
 }]
}

この状況においてエンティティの種類を指定しない場合、次のエラーが発生する可能性があります: "EdmEntityObject passed should have the key property value set."。

参照

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

次の方法で共有

Web API アクションの使用

バインドされていないアクション

バインドされたアクション

テーブルにバインドされたアクション

テーブルコレクションにバインドされたアクション

カスタムアクションの使用

カスタムアクションの例: 取引先担当者にメモを追加

テーブルタイプパラメーターを指定する

参照

その他のリソース

次の方法で共有

Web API アクションの使用

バインドされていないアクション

バインドされたアクション

テーブルにバインドされたアクション

テーブル コレクションにバインドされたアクション

カスタム アクションの使用

カスタム アクションの例: 取引先担当者にメモを追加

テーブル タイプ パラメーターを指定する

参照

その他のリソース

テーブルコレクションにバインドされたアクション

カスタムアクションの使用

カスタムアクションの例: 取引先担当者にメモを追加

テーブルタイプパラメーターを指定する