Web API 機能およびアクションのサンプル

[アーティクル]
03/03/2017

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

このサンプルグループは、バインドされた関数とバインドされていない関数およびアクションを実行する方法を示します。このアクションには Microsoft Dynamics 365 Web API を使用するカスタムアクションが含まれます。このサンプルは次の言語に対する別個のプロジェクトとして実装されます。

このトピックは、より高度でニュートラル言語レベルの構造と内容を説明します。このトピックに説明されている操作を実行する方法に関する言語固有の実装の詳細については、上記にリンクされたサンプルトピックを確認してください。

説明

このサンプルは次の主要なセクションに分かれています。それには関連する概念的なトピックでより詳しく説明される Web API 関数とアクションの処理が含まれます。

トピックセクション	関連するトピック
サンプルデータ
パラメーターなしでバインドされていない関数を使用する	バインドされていない関数 WhoAmI Function systemuser EntityType
パラメーターを使用するバインドされていない関数を使用する	バインドされていない関数 GetTimeZoneCodeByLocalizedName Function
パラメーターなしでバインドされた関数を使用する	バインドされた関数 CalculateTotalTimeIncident Function
パラメーターを使用するバインドされていないアクションを使用する	バインドされていないアクション WinOpportunity Action opportunity EntityType
パラメーターを使用するバインドされているアクションを使用する	バインドされたアクション AddToQueue Action WhoAmI Function systemuser EntityType letter EntityType
パラメーターを使用するバインドされているカスタムアクションを使用する	カスタムアクションの使用バインドされたアクション contact EntityType
パラメーターを使用するバインドされていないカスタムアクションを使用する	カスタムアクションの使用バインドされていないアクション account EntityType
ユーザー定義アクション例外の処理	カスタムアクションの使用バインドされていないアクション contact EntityType

次のセクションには、Dynamics 365 Web API 操作の実行に関する簡単な説明が、対応する HTTP メッセージおよび関連するコンソール出力と共に含まれています。

サンプルデータ

このサンプルでの操作が確実に実行されるために、まず Dynamics 365 サーバーにサンプルデータを作成します。これらのサンプルデータは、ユーザーがレポートの削除をしないという選択をしない限りサーバーから削除されます。このサンプルのデータは、次のように個別に作成されます。

取引先企業 (例: Fourth Coffee) を作成し、30 分のタスクが 3 回 (合計 90 分) あるインシデントと関連付けます。タスクを作成された後、それらは完了としてマークされます。この操作は、これらの 3 つのタスクを完了するために必要とした合計時間を計算します。
```
{
  title: "Sample Case",
  "customerid_account@odata.bind": accountUri,
  Incident_Tasks: [
   {
    subject: "Task 1",
    actualdurationminutes: 30
   },
   {
    subject: "Task 2",
    actualdurationminutes: 30
   },
   {
    subject: "Task 3",
    actualdurationminutes: 30
   }
  ]
 };
```
取引先企業を作成し、営業案件と関連付けます。この営業案件は、サンプル操作内で受注案件としてマークされます。
```
{
 name: "Sample Account for WebAPIFunctionsAndActions sample",
 opportunity_customer_accounts: [{
  name: "Opportunity to win"
 }]
};
```
レター活動を作成します。レターは、サンプル操作内で、現在のユーザーのキューに追加されます。
```
{
  description: "Example letter"
}
```
サンプル操作内の sample_AddNoteToContact カスタムアクションと共に使用する、取引先担当者を作成します。
```
{
  firstname: "Jon",
  lastname: "Fogg"
}
```

サンプルの操作

このトピックのサンプル操作は次の方法で組織されます。

関数の操作: これらの操作はパラメーターを受け入れるか受け入れないかに関係なく、バインドされた関数とバインドされていない関数を示します。
アクションの操作: これらの操作はパラメーターを受け入れるか受け入れないかに関係なく、バインドされたアクションとバインドされていないアクションを示します。
ユーザー定義アクション: これらの操作は、バインドされたアクションとバインドされていないアクションを示し、ユーザー定義のエラーの例外を処理する方法を示します。

関数に関する作業

関数は、副作用がない操作です。関数には、エンティティインスタンスまたはエンティティコレクションにバインドされている場合があります。クエリ関数はバインドされることはありません。詳細については、「Web API 関数の使用」を参照してください。このセクションは、バインドされた関数とバインドされていない関数が使用される方法、およびパラメーターが受け渡される方法を示します。

パラメーターなしでバインドされていない関数を使用する

WhoAmI Function を使用している現在のユーザーのフルネームを取得するために、バインドされていない関数を使用します。この操作はパラメーターを受け取らないバインドされていない関数を呼び出す方法を示します。この操作は、現在のユーザーのフルネームを返します。

WhoAmI Function に対する要求と応答を取得します。

HTTP 要求

GET http://cc_WebAPI_ServiceURI/WhoAmI HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP 応答

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 273

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
   "BusinessUnitId":"0d6cc84a-d3f6-e511-80d0-00155da84802",
   "UserId":"b08dc84a-d3f6-e511-80d0-00155da84802",
   "OrganizationId":"0f47eae2-a906-4ae4-9215-f09875979f6a"
}

パラメーターを使用するバインドされていない関数を使用する

バインドされていない関数を使用してタイムゾーンコードを取得します。この操作はパラメーターを受け取るバインドされていない関数を呼び出す方法を示します。この操作は指定されたタイムゾーンの現在のタイムゾーンコードを返します。詳細:関数にパラメーターを渡す

HTTP 要求

GET http://cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific%20Standard%20Time'&@p2=1033 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP 応答

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 154

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.GetTimeZoneCodeByLocalizedNameResponse",
   "TimeZoneCode":4
}

コンソール出力

Unbound function: GetTimeZoneCodeByLocalizedName
    Function returned time zone Pacific Standard Time, with code '4'.

パラメーターなしでバインドされた関数を使用する

バインドされた関数を使用して、インシデントのタスクすべてを完了するために必要とされた合計時間を取得します。この操作はパラメーターを受け取らないバインドされた関数を呼び出す方法を示します。この操作は、インシデントがすべてのタスクを終了するために必要とされた合計時間 (分) を返します。この関数は、このサンプルプログラム用に作成されたインシデントデータも使用します。詳細:バインドされた関数

HTTP 要求

GET http://cc_WebAPI_ServiceURI/incidents(3d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP 応答

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 148

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse",
   "TotalTime":90
}

コンソール出力

Bound function: CalculateTotalTimeIncident
    Function returned 90 minutes - total duration of tasks associated with the incident.

アクションに関する作業

操作は、副作用を許可する操作です。アクションはバインドされているか、またはバインドされていません。詳細については、「Web API アクションの使用」を参照してください。このセクションは、バインドされたアクションとバインドされていないアクションが使用される方法、およびパラメーターが受け渡される方法を示します。また、ユーザー定義のアクションが使用される方法と、これらのユーザー定義のアクションでの例外を処理する方法も示します。

パラメーターを使用するバインドされていないアクションを使用する

一連のパラメーターを受け取るバインドされていないアクションを使用します。この操作は、営業案件をクローズし、WinOpportunity Action の呼び出しにより受注したとマークします。先ほどこのプログラムで、opportunity EntityType がサンプルデータとして作成されました。詳細:バインドされていないアクション

HTTP 要求

POST http://cc_WebAPI_ServiceURI/WinOpportunity HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

{
   "Status":3,
   "OpportunityClose":{
      "subject":"Won Opportunity",
      "opportunityid@odata.bind":"http://cc_WebAPI_ServiceURI/opportunities(47920da5-fb4a-e611-80d5-00155da84802)"
   }
}

HTTP 応答

HTTP/1.1 204 No Content
OData-Version: 4.0

コンソール出力

Unbound Action: WinOpportunity
    Opportunity won.

パラメーターを使用するバインドされているアクションを使用する

パラメーターを受け取るバインドされているアクションを使用します。この操作は、現在のユーザーのキューにレターを追加します。これを達成するには、WhoAmI Function およびsystemuser EntityType を、現在のユーザーのキューへの参照を取得するために使用します。また letter EntityType への参照が必要です。先ほどこのプログラムで、この手紙がサンプルデータとして作成されました。次に、バインドされた AddToQueue Action が呼び出されて、現在のユーザーのキューにレターが追加されます。詳細:バインドされたアクション

HTTP 要求

POST http://cc_WebAPI_ServiceURI/queues(1f7bcc50-d3f6-e511-80d0-00155da84802)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 110

{
   "Target":{
      "activityid":"4c920da5-fb4a-e611-80d5-00155da84802",
      "@odata.type":"Microsoft.Dynamics.CRM.letter"
   }
}

HTTP 応答

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 170

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
   "QueueItemId":"67bdfabd-fc4a-e611-80d5-00155da84802"
}

コンソール出力

Bound Action: AddToQueue
    QueueItemId returned from AddToQueue Action: 67bdfabd-fc4a-e611-80d5-00155da84802

ユーザー定義アクションの操作

ソリューションのユーザー定義アクションを定義する場合、Dynamics 365 Web API を使用して呼び出します。カスタムアクションに含まれる操作に副作用があるかどうかにかかわらず、それらの操作はデータを変更する可能性があり、したがって関数ではなくアクションと見なされます。カスタム関数を作成する方法はありません。詳細:カスタムアクションの使用。

このサンプルでは、2 つのカスタムアクションが用意されています。両方にパラメーターが必要ですが、1 つはバインドされていて、もう 1 つはバインドされていません。

sample_AddNoteToContact: 2 つのパラメーターを受け取るバインドされたユーザー定義アクション。 1 つは NoteTitle で、もう 1 つは NoteText です。このユーザー定義アクションは、contact EntityType にメモを追加します。以下は、このユーザー定義アクションの [情報] ページのスクリーンショットです。
sample_CreateCustomer: 作成されている顧客の種類に応じて異なるパラメーターが必要な、バインドされていないユーザー定義アクション。たとえば、AccountType が ”取引先企業" の場合、AccountName パラメーターのみが必要です。AccountType が、"取引先担当者" の場合、ContactFirstName および ContactLastName パラメーターが必要です。以下は、このユーザー定義アクションの [情報] ページのスクリーンショットです。

パラメーターを使用するバインドされているカスタムアクションを使用する

この例では、sample_AddNoteToContact ユーザー定義アクションが呼び出され、必要なパラメーターを使用するユーザー定義エンティティにバインドされます。このユーザー定義アクションは、既存の取引先担当者にメモを追加します。このアクションは、annotationid プロパティを持つエンティティを返します。メモが追加されていることを示すために、annotationid が使用されてメモの情報を要求します。

アクションの要求と応答。

HTTP 要求

POST http://cc_WebAPI_ServiceURI/contacts(4d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.sample_AddNoteToContact HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 80

{
   "NoteTitle":"The Title of the Note",
   "NoteText":"The text content of the note."
}

HTTP 応答

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 149

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations/$entity",
   "annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802"
}

コメントの要求と応答。

HTTP 要求

GET http://cc_WebAPI_ServiceURI/annotations(ba146d0b-fd4a-e611-80d5-00155da84802)?$select=subject,notetext&$expand=objectid_contact($select=fullname) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP 応答

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: 450

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations(subject,notetext,objectid_contact,objectid_contact(fullname))/$entity",
   "@odata.etag":"W/\"622978\"",
   "subject":"The Title of the Note",
   "notetext":"The text content of the note.",
   "annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802",
   "objectid_contact":{
      "@odata.etag":"W/\"622968\"",
      "fullname":"Jon Fogg",
      "contactid":"4d920da5-fb4a-e611-80d5-00155da84802"
   }
}

コンソール出力

Custom action: sample_AddNoteToContact
    A note with the title 'The Title of the Note' and the content 'The text content of the note.' was created and associated with the contact Jon Fogg.

パラメーターを使用するバインドされていないカスタムアクションを使用する

この操作は sample_CreateCustomer ユーザー定義アクションを呼び出して、”取引先企業” 顧客を作成します。必須パラメーターは account の CustomerType に渡されます。

HTTP 要求

POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103

{
   "CustomerType":"account",
   "AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}

HTTP 応答

HTTP/1.1 204 No Content
OData-Version: 4.0

ユーザー定義アクション例外の処理

この例は、ユーザー定義アクションがユーザー定義のエラーメッセージを返せることを示します。ユーザー定義の例外を、標準の例外と同じ方法で処理します。sample_CreateCustomer ユーザー定義のアクションからユーザー定義のエラーメッセージを取得するには、この例では "取引先担当者" 顧客を作成します。ただし、この CustomerType パラメーターに関しては、意図的に間違ったパラメーターを渡しています。この操作は次に、例外をキャッチし、エラーメッセージを表示し、次に同じプログラムを続行します。

HTTP 要求

POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103

{
   "CustomerType":"contact",
   "AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}

HTTP 応答

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 2760

{
   "error":{
      "code":"",
      "message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
      "innererror":{
         "message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
         ...[truncated]
      }
   }
}

コンソール出力

Expected custom error: ContactFirstName and ContactLastName are required when CustomerType is contact.

Web API 機能およびアクションのサンプル

説明

サンプルデータ

サンプルの操作

関数に関する作業

パラメーターなしでバインドされていない関数を使用する

パラメーターを使用するバインドされていない関数を使用する

パラメーターなしでバインドされた関数を使用する

アクションに関する作業

パラメーターを使用するバインドされていないアクションを使用する

パラメーターを使用するバインドされているアクションを使用する

ユーザー定義アクションの操作

パラメーターを使用するバインドされているカスタムアクションを使用する

パラメーターを使用するバインドされていないカスタムアクションを使用する

ユーザー定義アクション例外の処理

関連項目

その他のリソース

Web API 機能およびアクションのサンプル

説明

サンプル データ

サンプルの操作

関数に関する作業

パラメーターなしでバインドされていない関数を使用する

パラメーターを使用するバインドされていない関数を使用する

パラメーターなしでバインドされた関数を使用する

アクションに関する作業

パラメーターを使用するバインドされていないアクションを使用する

パラメーターを使用するバインドされているアクションを使用する

ユーザー定義アクションの操作

パラメーターを使用するバインドされているカスタム アクションを使用する

パラメーターを使用するバインドされていないカスタム アクションを使用する

ユーザー定義アクション例外の処理

関連項目

その他のリソース

サンプルデータ

パラメーターを使用するバインドされているカスタムアクションを使用する

パラメーターを使用するバインドされていないカスタムアクションを使用する