웹 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. 저작권 정보