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

アクションと関数は、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 アクションは、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 を使用してテーブル行をマージする

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

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

CSDL $metadata ドキュメントでは、Action要素がバインドされたアクションを表す場合、IsBound属性にtrueという値があります。アクション内で定義された最初の 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>

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

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

次の例は、 AddToQueue アクションを使用してキューに文字を追加する方法を示しています。 Target パラメーター型が特定されていない (mscrm.crmbaseentity) ため、Microsoft.Dynamics.CRM に名前空間を含むエンティティの完全名として@odata.type プロパティ値を用いて、オブジェクトの型を明示的に宣言する必要があります。例では、 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>

このエンティティコレクションバインドアクションは、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)} 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.+<エンティティの論理名>のパターンに従います。

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

他の 2 つの例はAddMembersTeamおよびRemoveMembersTeamのアクションです。なぜなら、Membersパラメーターはsystemuserエンティティ型のコレクションであり、その主キーをprincipalエンティティ型から継承しているからです。コレクション内の単一の systemuser を表すために次の JSON を渡して場合、エンティティが systemuser であり、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 2025-10-04

次の方法で共有

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

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

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

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

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

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

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

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

こちらも参照ください

フィードバック

その他のリソース

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

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

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