웹 API 작업 사용

  • 아티클

 

게시 날짜: 2017년 1월

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

작업 및 기능은 웹 API를 사용하여 수행할 수 있는 재사용 가능한 작업을 나타냅니다.Web API Action Reference에 나열된 작업이 있는 POST 요청을 사용하여 부작용이 있는 작업을 수행합니다. 또한 사용자 지정 작업을 정의할 수 있으며 사용할 준비가 되어 있습니다.

이 항목의 내용

바인딩되지 않은 작업

바인딩된 작업

사용자 지정 작업 사용

엔터티 매개변수 유형 지정

바인딩되지 않은 작업

작업은 d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl에 정의됩니다. 예를 들어, 다음은 CSDL에 표시되는 WinOpportunity Action의 정의입니다.

<Action Name="WinOpportunity">
  <Parameter Name="OpportunityClose" Type="mscrm.opportunityclose" Nullable="false" />
  <Parameter Name="Status" Type="Edm.Int32" Nullable="false" />
</Action>

WinOpportunity 작업은 조직 서비스를 사용하여 WinOpportunityRequest에 대응합니다. 이 작업을 사용하여 영업 기회 상태를 성공으로 설정하고 opportunityclose EntityType을 만들어 이벤트를 기록합니다. 이 작업은 반환 값을 포함하지 않습니다. 성공하면 작업이 완료됩니다.

OpportunityClose 매개 변수는 작업에서 만들려면 opportunityclose 엔터티의 JSON 표현이 필요합니다. 이 엔터티는 opportunityid 단일 값의 내비게이션 속성을 발행하는 영업 기회와 관련이 있어야 합니다.JSON에서는 만들 때 엔터티 연결에서 설명한 대로 @odata.bind 주석을 사용하여 설정됩니다.

Status 매개 변수는 닫혔을 때 opportunity에 대한 상태로 설정해야 합니다.opportunity EntityTypestatuscode 속성에서 이를 위한 기본값을 찾을 수 있습니다.성공 옵션의 값은 3입니다.성공을 나타내는 상태 설명 옵션이 하나 밖에 없을 때는 이 값을 설정할 필요가 있는 이유가 궁금할 수 있을 것입니다. 이유는 Big Win 또는 Small Win 같이 성공을 나타내는 사용자 지정 상태 옵션을 정의할 수 있으므로 값은 해당 상황에서 3과 다를 수 있습니다.

다음 예제는 HTTP 요청이며 b3828ac8-917a-e511-80d2-00155d2a68d2의 opportunityid 값을 사용하여 영업 기회에 대한 WinOpportunity 작업 호출에 응답합니다.

  • 요청

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

{
 "Status": 3,
 "OpportunityClose": {
  "subject": "Won Opportunity",
  "opportunityid@odata.bind": "cc_WebAPI_ServiceURI/opportunities(b3828ac8-917a-e511-80d2-00155d2a68d2)"
 }
}

  • 응답

    HTTP/1.1 204 No Content
OData-Version: 4.0

바인딩된 작업

d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl에서 Action 요소가 바인딩된 작업을 나타내면 값이 true인 IsBound 특성이 있습니다. 작업 내에 정의된 첫 번째 매개 변수 요소는 작업이 바인딩된 엔터티를 나타냅니다. 매개 변수의 Type 특성이 컬렉션이면 작업은 엔터티 컬렉션으로 바인딩됩니다. 예를 들어, 다음은 CSDL에 표시되는 AddToQueue Action의 정의입니다.

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

이 바인딩 작업은 조직 서비스에서 사용하는 AddToQueueRequest와 동일합니다. 웹 API에서 이 작업은 AddToQueueRequest.DestinationQueueId 속성을 나타내는 queue EntityType에 바인딩됩니다. 이 작업은 여러 추가 매개 변수를 받고 조직 서비스에서 반환된 AddToQueueResponse에 해당하는 AddToQueueResponse ComplexType를 반환합니다. 작업이 복합 유형을 반환하면 복잡 유형의 정의가 CSDL에서 작업 바로 위에 나타납니다.

바인딩 작업은 첫 번째 매개 변수 값을 설정하기 위해 URI를 사용하여 호출해야 합니다. 명명된 매개 변수 값으로 설정할 수는 없습니다.

바인딩 함수를 호출할 때 Microsoft.Dynamics.CRM 네임 스페이스를 포함하여 함수의 전체 이름을 포함해야 합니다. 전체 이름을 포함하지 않을 경우 다음 오류가 발생합니다. Status Code:400 Request message has unresolved parameters.

다음 예제에서는 큐에 문자를 추가하기 위해 AddToQueue Action을 사용하는 방법을 보여줍니다.Target 매개 변수 유형은 특정하지 않으므로(mscrm.crmbaseentity) Microsoft.Dynamics.CRM 네임스페이스를 포함하여 엔터티의 전체 이름의 @odata.type 속성 값을 사용하여 개체의 유형을 명시적으로 선언해야 합니다. 이 경우, Microsoft.Dynamics.CRM.letter.추가 정보:엔터티 매개변수 유형 지정

  • 요청

    POST cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

사용자 지정 작업 사용

조직 또는 솔루션을 위한 사용자 지정 작업을 정의하는 경우 d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl에도 포함됩니다. 응용 프로그램에서 사용자 지정 도구를 사용하여 작업을 만드는 자세한 내용은 TechNet 항목작업을 참조하십시오. 사용자 지정 작업 만들기 및 사용에 대한 자세한 내용은 사용자 고유의 작업 만들기를 참조하십시오.

사용자 지정 작업에 포함된 작업에 부작용이 있는지 여부에 관계 없이 데이터를 수정할 수 있으므로 함수라기 보다는 작업으로 간주됩니다. 사용자 지정 함수를 만드는 방법은 없습니다.

사용자 지정 작업의 예: 연락처에 메모 추가

특정 연락처에 새 메모를 추가하는 사용자 지정 작업을 만들어 보겠습니다. 다음과 같은 속성을 사용하여 연락처 엔터티에 바인딩된 사용자 지정 작업을 만들 수 있습니다.

UI 레이블

값

프로세스 이름

AddNoteToContact

고유 이름

new_AddNoteToContact

엔터티

연락처

범주

작업

프로세스 인수

이름

유형

필수 참석자

방향

NoteTitle

문자열

필수 참석자

Input

NoteText

문자열

필수 참석자

Input

NoteReference

EntityReference

필수 참석자

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 cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$metadata#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

엔터티 매개변수 유형 지정

작업에서 매개변수로 엔터티가 필요하고 엔터티의 유형을 잘 모르면 @odata.type 속성을 사용하여 엔터티 유형을 지정해야 합니다. 이 속성의 값은
Microsoft.Dynamics.CRM.+<엔터티 논리 이름> 패턴을 따르는 정규화된 엔터티의 이름입니다.

위 바인딩된 작업 섹션에서 보았던 것과 같이 AddToQueue Action에 대한 Target 매개 변수는 활동입니다. 그러나 모든 활동은 activitypointer EntityType에서 상속되므로 "@odata.type": "Microsoft.Dynamics.CRM.letter" 속성을 엔터티 JSON에 포함하여 엔터티 유형이 문자임을 지정해야 합니다.

다른 두 가지 예는 AddMembersTeam Action 및 RemoveMembersTeam Action입니다. Members 매개변수는 ownerid 기본 키를 principal EntityType에서 상속하는 systemuser EntityType의 집합이기 때문입니다. 다음 JSON을 전달하여 집합에 단일 시스템 사용자를 나타내면 엔터티가 시스템 사용자이며 역시 주 엔터티 유형에서 상속된 team EntityType이 아니라는 것을 명시할 수 있습니다.

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

여기에서 엔터티 유형을 지정하지 않으면 "EdmEntityObject passed should have the key property value set."의 오류를 얻을 수 있습니다.

참고 항목

웹 API 함수 및 동작 샘플(C#)
웹 API 함수 및 동작 샘플(클라이언트 쪽 JavaScript)
웹 API를 사용하여 작업 수행
HTTP 요청 및 처리 오류 작성
웹 API를 사용하여 데이터 쿼리
웹 API를 사용하여 엔터티 만들기
웹 API를 사용하여 엔터티 검색
웹 API를 사용하여 엔터티 업데이트 및 삭제
웹 API를 사용하여 엔터티 연결 및 연결 해제
웹 API 기능 사용
웹 API를 사용하여 일괄 작업 실행
웹 API를 사용하여 다른 사용자를 가장
웹 API를 사용하여 조건부 작업을 수행

Microsoft Dynamics 365

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