Web API アクションを使用する

Web API アクションを使用して、Microsoft Dataverse で副作用のある再利用可能な操作を実行します。データの変更、ビジネスロジックのトリガー、またはカスタムプロセスの呼び出しを行うアクションを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 アクションは、SDK for .NET を使用する場合の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 を使用してテーブル行をマージする」を参照してください。

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

アクションは、エンティティまたはエンティティコレクションにバインドできます。アクションをエンティティにバインドする方が一般的です。

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

バインドされた関数を呼び出す場合は、 Microsoft.Dynamics.CRM 名前空間を含め、関数の完全な名前を含めます。完全な名前を含めない場合は、次のエラーが表示されます: Status Code:400 Request message has unresolved parameters。

テーブルに関連付けられたアクション

次の例は、 AddToQueue アクションの定義と、エンティティにバインドされたアクションとしての CSDL の複合型 AddToQueueResponse を示しています。

<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>

このエンティティバインドアクションは、SDK for .NET で使用される AddToQueueRequest と同じです。 Web API では、このアクションは、queue.AddToQueueRequest プロパティを表すDestinationQueueId エンティティ型にバインドされます。

このアクションは、さらにいくつかのパラメーターを受け取り、SDK for .NET によって返される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"
}

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

エンティティコレクションにバインドされたアクションを見つけることはあまり一般的ではありません。次の一覧には、見つかる可能性のあるいくつかのアクションが含まれています。

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>

このエンティティコレクションバインドアクションは、SDK for .NET で使用される 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 ラベル	価値
プロセス名	連絡先にメモを追加
一意の名前	新規_メモを連絡先に追加
エンティティ	お問い合わせ
カテゴリ	目的

プロセス引数

名前	タイプ	必須	通信方向
注記タイトル	String	必須	Input
NoteText	String	必須	Input
NoteReference	EntityReference	必須	アウトプット

手順

名前	ステップの種類	Description
メモを作成する	レコードの作成	Title = {NoteTitle(Arguments)} Note Body = {NoteText(Arguments)} 関して = {Contact{Contact}}
メモへの参照を返す	値の割り当て	NoteReference 値 = {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.+<エンティティの論理名>のパターンに従います。

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

AddMembersTeam パラメーターはエンティティ型のコレクションであり、RemoveMembersTeam エンティティ型からMembers主キーを継承するsystemuserエンティティ型のコレクションであるため、他の 2 つの例がowneridアクションとprincipalアクションです。次の JSON を渡すことでコレクション内の 1 人のシステムユーザーを表す場合、そのエンティティはシステムユーザーであり、team エンティティ型ではなく、プリンシパルエンティティ型から継承していることが明確です。

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

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

こちらも参照ください

フィードバック

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

Last updated on 2026-03-14

次の方法で共有

Web API アクションを使用する

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

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

テーブルに関連付けられたアクション

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

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

カスタム アクションの例: 連絡先にメモを追加する

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

こちらも参照ください

フィードバック

その他のリソース

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

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

カスタムアクションの例: 連絡先にメモを追加する