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 アクションは、.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.0/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.0/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

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

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

Dynamics 365 for SalesFulfillSalesOrder

エンティティ コレクションにバインドされたアクションの例として、以下は 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.1/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.1/$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 つの例は AddMembersTeamRemoveMembersTeam アクションです。 コレクション内の単一のシステムユーザーを表すために次の 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 分かかります。 個人データは収集されません (プライバシー ステートメント)。