웹 API 기능 사용

게시 날짜: 2017년 1월

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

함수 및 작업은 웹 API를 사용하여 수행할 수 있는 재사용 가능한 작업을 나타냅니다. 웹 API에는 다음 두 가지 유형의 함수가 있습니다.

• Functions
  Web API Function Reference에 나열된 함수가 있는 GET 요청을 사용하여 부작용이 없는 작업을 수행합니다. 이러한 함수는 일반적으로 데이터를 검색합니다. 컬렉션 또는 복합 형식을 반환합니다. 이러한 각 함수는 조직 서비스에 해당하는 메시지가 있습니다.

• 쿼리 함수
  Web API Query Function Reference에 나열된 함수를 사용하여 작성한 쿼리의 속성과 값을 평가합니다. 각 함수에는 해당하는 ConditionOperator 값이 있습니다.

이 항목의 내용

함수에 매개 변수 전달

함수에 엔터티 참조를 전달

바인딩 및 바인딩 해제 함수

함수를 사용하여 쿼리를 작성합니다.

함수에 매개 변수 전달

매개 변수가 필요한 함수의 경우 가장 좋은 방법은 매개 변수를 사용하여 값을 전달하는 것입니다. 예를 들어, GetTimeZoneCodeByLocalizedName Function을 사용할 때는 LocalizedStandardName 및 LocaleId 매개 변수 값을 포함해야 합니다. 따라서 여기에 나와 있는 것처럼 다음 인라인 구문을 사용할 수 있습니다.

GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

그러나 쿼리 매개 변수 #204로서의 DateTimeOffset 문서에서 설명한 대로 인라인 구문에는 DateTimeOffset 값 사용 시 열기 문제가 있습니다.

따라서 다음 코드 예제와 같이 매개 변수로 값을 전달하는 것이 좋습니다. 이 방법을 사용하면 DateTimeOffset에 적용되는 열기 문제를 방지할 수 있습니다.

GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033

매개 변수 별칭을 사용하면 매개 변수 값을 재사용하여 매개 변수 값이 여러 번 사용될 때 URL의 총 길이를 줄일 수 있습니다.

함수에 엔터티 참조를 전달

특정 함수는 기존 엔터티에 대한 참조를 전달해야 합니다. 예를 들어 다음 함수는 crmbaseentity EntityType이 필요한 매개 변수를 가집니다.

기존 엔터티에 참조를 전달할 때 엔터티에 대한 URI에 @odata.id 주석을 사용합니다. 예를 들어 RetrievePrincipalAccess Function을 사용하는 경우 다음의 URI를 사용하여 특정 연락처에 대한 검색 액세스를 지정할 수 있습니다.

GET cc_WebAPI_ServiceURI/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'} 

@odata.id 주석은 전체 URI일 수 있지만, 상대 URI 또한 작동합니다.

바인딩 및 바인딩 해제 함수

Web API Function Reference에 있는 함수만 바인딩할 수 있습니다. 쿼리 함수는 절대로 바인딩되지 않습니다.

바인딩 함수

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

<ComplexType Name="CalculateTotalTimeIncidentResponse">
  <Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
  <Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
  <ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>

이 바인딩 함수는 조직 서비스에서 사용하는 CalculateTotalTimeIncidentRequest와 동일합니다. 웹 API에서 이 함수는 CalculateTotalTimeIncidentRequest.IncidentId 속성을 나타내는 incident EntityType에 바인딩됩니다.CalculateTotalTimeIncidentResponse를 반환하는 대신 이 함수는 CalculateTotalTimeIncidentResponse ComplexType을 반환합니다. 함수가 복합 유형을 반환하면 정의가 CSDL에서 함수 정의 바로 위에 나타납니다.

바운딩 함수를 호출하려면 URL에 함수의 전체 이름을 추가하고 함수 이름 다음에 있는 괄호 안에 명명된 매개 변수를 포함합니다. 전체 함수 이름은 네임스페이스 Microsoft.Dynamics.CRM을 포함합니다. 바인딩되지 않은 함수는 전체 이름을 사용해서는 안 됩니다.

다음 예제는 문제 엔터티에 바인딩되는 CalculateTotalTimeIncident Function을 사용하는 예제를 보여줍니다.

• 요청

  GET cc_WebAPI_ServiceURI/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• 응답

  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.CalculateTotalTimeIncidentResponse","TotalTime":30
  }
  

바인딩 해제 함수

WhoAmI Function은 엔터티에 바인딩되지 않습니다. 이 함수는 CSDL에 IsBound 특성 없이 정의됩니다.

<ComplexType Name="WhoAmIResponse">
  <Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
  <Property Name="UserId" Type="Edm.Guid" Nullable="false" />
  <Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
<Function Name="WhoAmI">
  <ReturnType Type="mscrm.WhoAmIResponse" Nullable="false" />
</Function>

이 함수는 WhoAmIRequest에 대응하며 조직 서비스에서 사용되는 WhoAmIResponse에 해당하는 WhoAmIResponse ComplexType을 반환합니다. 이 함수에는 매개 변수가 없습니다.

바인딩되지 않은 함수를 호출할 때는 다음 예제와 같이 함수 이름만 사용합니다.

• 요청

  GET cc_WebAPI_ServiceURI/WhoAmI() HTTP/1.1
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• 응답

  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.WhoAmIResponse",
   "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1",
   "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1",
   "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1"
  }
  

함수를 사용하여 쿼리를 작성합니다.

함수를 사용하여 쿼리에서 반환되는 데이터를 제어하는 방법은 두 가지가 있습니다. 특정 함수를 사용하면 반환하는 열 또는 조건을 제어할 수 있으며 쿼리 함수를 사용하여 쿼리의 조건을 평가할 수 있습니다.

구성 가능한 함수

Web API Function Reference에 나열된 일부 함수는 엔터티 컬렉션을 반환합니다. 이러한 함수의 하위 집합은 작성 가능하며 결과에 어떤 열을 반환할지를 제어하는 추가 $select 또는 $filter 시스템 쿼리 옵션을 포함할 수 있습니다. 이러한 함수는 CSDL에서 IsComposable 특성을 갖습니다. 이러한 각 함수에는 조직 서비스에서 ColumnSet 또는 QueryBase 유형 매개 변수를 받는 동반 메시지가 있습니다.OData 시스템 쿼리 옵션은 동일한 기능을 제공하므로 이러한 함수는 조직 서비스의 동반 메시지와 동일한 매개 변수를 사용하지 않습니다. 다음 표는 이번 릴리스의 작성 가능한 함수 목록을 보여줍니다.

쿼리 함수

Web API Query Function Reference에 나열된 함수는 쿼리를 작성하는 데 사용됩니다. 이러한 함수는 표준 쿼리 함수와 유사한 방식으로 사용할 수 있지만 중요한 몇 가지 차이가 있습니다.

함수의 전체 이름을 사용하고 매개 변수 이름을 포함해야 합니다. 다음 예제는 LastXHours Function를 사용하여 지난 12시간 동안 수정된 모든 거래처 엔터티를 반환하는 방법을 보여줍니다.

GET cc_WebAPI_ServiceURI/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

참고 항목

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

Microsoft Dynamics 365

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