웹 API 함수 및 동작 샘플

  • 아티클

 

게시 날짜: 2017년 1월

적용 대상: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

이 그룹의 샘플은 Microsoft Dynamics 365 웹 API를 사용하여 사용자 지정 작업을 포함하는 바운드 및 언바운드 함수와 동작을 수행하는 방법을 기술합니다. 이 샘플은 다음 언어에 대해 별도 프로젝트로 구현됩니다.

이 항목에서는 샘플의 구조와 내용을 높은 수준에서 중립적인 언어 수준으로 설명합니다. 이 항목에 설명된 작업을 수행하는 방법에 대해 각 언어 관련 구현 세부 정보는 위의 링크된 샘플 항목을 검토하십시오.

시연

이 샘플은 웹 관련 개념 항목에서 보다 자세히 다룰 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 웹 API 작업과 해당 HTTP 메시지 및 관련 콘솔 출력에 대한 간략한 설명을 담고 있습니다.

샘플 데이터

이 샘플에 있는 작업을 제대로 수행하려면 먼저 Dynamics 365 서버에서 샘플 데이터를 만들어야 합니다. 사용자가 파일을 삭제하지 않도록 선택하지 않으면 이러한 예제 데이터는 서버에서 삭제됩니다. 이 샘플에서 데이터는 다음과 같이 개별적으로 생성됩니다.

  • 거래처(예: Fourth Coffee)를 만들고 인시던트에 연결합니다. 이 작업은 30분 정도 걸립니다(총 90 분). 작업이 만들어지면 완료됨으로 표시됩니다. 작업은 이러한 세 가지 작업을 완료하는 데 걸린 총 시간을 계산합니다.

    {
  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"
}

샘플 작업

이 항목의 샘플 작업은 다음과 같이 구성됩니다.

  • 함수 작업: 이러한 작업은 매개 변수를 허용하거나 허용하지 않는 바운드와 언바운드 함수를 표시합니다.

  • 동작 작업: 이러한 작업은 매개 변수를 허용하거나 허용하지 않는 바운드와 언바운드 동작을 표시합니다.

  • 사용자 지정 동작: 이러한 작업은 바운드 및 언바운드 동작 및 사용자 지정 오류 예외를 처리하는 방법을 표시합니다.

함수 작업

Functions는 부작용이 없는 작업입니다. 함수는 엔터티 인스턴스 또는 엔터티 컬렉션에 바인딩될 수 있습니다. 쿼리 함수는 절대로 바인딩되지 않습니다. 자세한 내용은 웹 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.

동작 작업

작업은 부작용이 있는 작업입니다. 동작은 바운드 또는 언바운드입니다. 자세한 내용은 웹 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 웹 API를 사용하여 호출할 수 있습니다. 사용자 지정 작업에 포함된 작업에 부작용이 있는지 여부에 관계 없이 데이터를 수정할 수 있으므로 함수라기 보다는 작업으로 간주됩니다. 사용자 지정 함수를 만드는 방법은 없습니다.추가 정보:사용자 지정 작업 사용.

이 샘플에는 두 가지 사용자 지정 동작이 있습니다. 두 동작 모두 매개 변수를 필요로 하지만 하나는 바운드이며 다른 하나는 언바운드입니다.

  • sample_AddNoteToContact: 두 개의 매개 변수를 사용하는 사용자 지정 바운드 동작입니다. 하나는 NoteTitle이고 다른 하나는 NoteText입니다. 이 사용자 지정 동작은 contact EntityType에 메모를 추가합니다. 아래는 사용자 지정 동작에 대한 정보 페이지의 스크린샷입니다.

    Custom Action - AddNoteToContact information

  • sample_CreateCustomer: 만든 고객의 유형에 따라 다른 매개 변수를 필요로 하는 언바운드 사용자 지정 동작입니다. 예를 들어, AccountType이 "account"이면 AccountName 매개 변수만 필요합니다.AccountType이 "contact"이면 ContactFirstName 및 ContactLastName 매개 변수가 필요합니다. 아래는 사용자 지정 동작에 대한 정보 페이지의 스크린샷입니다.

    Custom Action - CreateCustomer information

매개 변수로 바운드 사용자 지정 동작 사용

이 예제에서는 필요한 매개 변수를 사용하여 연락처 엔터티에 바인딩된 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.

매개 변수로 언바운드 사용자 지정 동작 사용

이 작업은 "account" 고객을 만들 수 있는 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 사용자 지정 동작에서 사용자 지정 오류 메시지를 가져오기 위해 이 예제에서는 "contact" 고객을 만듭니다. 그러나 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.

참고 항목

Microsoft Dynamics 365 웹 API 사용
웹 API 기능 사용
웹 API 작업 사용
웹 API 함수 및 동작 샘플(C#)
웹 API 함수 및 동작 샘플(클라이언트 쪽 JavaScript)

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 저작권 정보