다음을 통해 공유

웹 API를 사용하여 조건부 작업을 수행

  • 아티클

 

게시 날짜: 2017년 1월

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

Microsoft Dynamics 365은 Etag라고 하는 표준 HTTP 리소스 버전 관리 메커니즘을 사용하는 조건부 작업 집합을 지원합니다.

이 항목의 내용

ETags

If-Match 및 If-None-Match 머리말

조건부 검색

upsert 작업 제한

낙관적 동시 실행 적용

ETags

HTTP 프로토콜은 리소스의 특정 버전을 식별하기 위해 엔터티 태그, 또는 줄여서 ETag를 정의합니다. Etag는 불투명한 식별자로 정확한 값은 구현에 따라 다릅니다. ETag 값은 두 가지 상황, 강력한 또는 취약한 유효성 검사 때 발생합니다. 강력한 유효성 검사는 특정 URI로 식별하는 고유한 리소스가 해당 ETag 값이 변경되지 않는 경우 바이너리 수준이 같다는 것을 나타냅니다. 취약한 유효성 검사는 리소스 표현이 동일한 ETag 값에 대해 의미가 같다는 것만 보장합니다.

Dynamics 365은 모든 엔터티 인스턴스에 대해 약한 검증 @odata.etag 속성을 생성합니다. 이 속성은 검색된 엔터티 레코드마다 자동으로 반환됩니다. 자세한 내용은 웹 API를 사용하여 엔터티 검색을 참조하십시오.

If-Match 및 If-None-Match 머리말

If-Match 및 If-None-Match 머리말을 ETag 값과 사용하여 현재 버전의 리소스가 마지막으로 검색한 것과 일치하는지, 이전 버전과 일치하는지, 또는 일치하는 버전이 없는지 여부를 확인할 수 있습니다. 이러한 비교는 조건 연산 지원의 기초를 형성합니다. Dynamics 365는 조건부 검색, 낙관적 동시 실행, 그리고 제한된 upsert 작업을 지원하는 Etag를 제공합니다.

경고

클라이언트 코드가 어떠한 특정 Etag 값에도 의미를 부여하거나,명백한 프로그램과 동등 또는 비동등 이상의 Etag 사이에 명백한 관계를 부여하지 않아야 합니다. 예를 들어, 리소스의 최신 버전에 대한 ETag 값이 이전 버전에 대한 ETag 값보다 클 것이 보장되지 않습니다. 또한 새 ETag 값을 생성하는 데 사용되는 알고리즘은 서비스 릴리스 간의 예고 없이 변경될 수 있습니다.

조건부 검색

Etag를 사용하여 동일한 레코드에 여러 번 액세스할 때마다 레코드 검색을 최적화할 수 있습니다. 이전에 레코드를 검색한 경우, ETag 값을 If-None-Match 머리말과 함께 전달하여 데이터가 마지막으로 검색된 후 변경되었는지 여부만 검색되도록 요청할 수 있습니다. 데이터가 변경되었으면, 요청은 요청 본문의 최신 데이터와 함께 200 HTTP 상태(OK)를 반환합니다. 데이터가 변경되지 않은 경우에는, 엔터티가 수정되지 않았음을 나타내기 위해 HTTP 상태 코드 304(Not Modified)가 반환됩니다. 다음의 예제 메시지 쌍은 데이터가 마지막으로 검색된 후 변경되지 않은 경우 00000000-0000-0000-0000-000000000001과 같은 accountid와 함께 거래처 엔터티에 대한 데이터를 반환합니다.

  • 요청

    GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=accountcategorycode,accountnumber,creditonhold,createdon,numberofemployees,name,revenue   HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: W/"468026"

  • 응답

    HTTP/1.1 304 Not Modified
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

upsert 작업 제한

upsert가 없는 경우 엔터티를 만들어 일반적으로 작동하거나 그렇지 않으면 기존 엔터티를 업데이트합니다. 그러나, 생성을 방지하거나 업데이트를 방지하기 위해 Etag를 사용하여 upsert를 더욱 제한할 수 있습니다.

upsert에서 만들기 방지

데이터를 업데이트하는 중이고 해당 엔터티가 의도적으로 삭제되었을 가능성이 있는 경우, 엔터티를 다시 만들고 싶지 않을 수 있습니다. 이를 방지하려면, '*'의 값을 사용하는 요청에 If-Match 헤더를 추가합니다.

  • 요청

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-Match: "*"

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

  • 응답
    엔터티가 있으면 204(No Content) 상태로 정상적인 응답을 얻을 수 있습니다. 엔터티가 없으면 404(Not Found) 상태로 다음 응답을 얻을 수 있습니다.

    HTTP/1.1 404 Not Found
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal

{
 "error": {
  "code": "",
  "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist",
  "innererror": {
   "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist",
   "type": "System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
   "stacktrace": <stack trace removed for brevity>
  }
 }
}

upsert에서 업데이트 방지

데이터를 삽입하는 경우, 동일한 id 값을 가진 레코드가 이미 시스템에 존재할 가능성이 있을 때 이를 업데이트하고 싶지 않을 수 있습니다. 이를 방지하려면, '*'의 값을 사용하는 요청에 If-None-Match 헤더를 추가합니다.

  • 요청

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: "*"

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

  • 응답
    엔터티가 없으면 204(No Content) 상태로 정상적인 응답을 얻을 수 있습니다. 엔터티가 있으면 412(Precondition Failed) 상태로 다음 응답을 얻을 수 있습니다.

    HTTP/1.1 412 Precondition Failed
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal

{
  "error":{
   "code":"",
   "message":"A record with matching key values already exists.",
   "innererror":{
    "message":"Cannot insert duplicate key.",
    "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
    "stacktrace":<stack trace removed for brevity>
    }
  }
}

낙관적 동시 실행 적용

낙관적 동시 실행을 사용하여 엔터티가 마지막으로 검색된 날 이후 수정되었는지 여부를 감지할 수 있습니다. 업데이트 또는 삭제하려는 엔터티가 검색 후 서버에서 변경된 경우, 업데이트 또는 삭제 작업 완료를 원치 않을 수 있습니다. 여기에 표시된 패턴을 적용하여 이 상황을 감지하고, 엔터티의 가장 최신 버전을 검색하고, 작업을 다시 시도할지 여부를 다시 평가하기 위해 필요한 조건을 적용할 수 있습니다.

삭제에 낙관적 동시 실행 적용

If-Match 머리말과 함께 전송된 ETag 값이 현재 값과 다르므로 accountid of00000000-0000-0000-0000-000000000001을 사용한 다음 거래처에 대한 삭제 요청은 실패하게 됩니다. 값이 일치할 경우, 204(No Content) 상태가 예상됩니다.

  • 요청

    DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • 응답

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "error":{
    "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.",
    "innererror":{
      "message":"The version of the existing record doesn't match the RowVersion property provided.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
"stacktrace":"  <stack trace details omitted for brevity>
    }
  }
}

업데이트에 낙관적 동시 실행 적용

If-Match 머리말과 함께 전송된 ETag 값이 현재 값과 다르므로 00000000-0000-0000-0000-000000000001의 accountid를 사용한 다음 거래처에 대한 업데이트 요청은 실패하게 됩니다. 값이 일치할 경우, 204 (No Content) 상태가 예상됩니다.

  • 요청

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"name":"Updated Account Name"}

  • 응답

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "error":{
    "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.",
    "innererror":{
      "message":"The version of the existing record doesn't match the RowVersion property provided.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
"stacktrace":"  <stack trace details omitted for brevity>
    }
  }
}

참고 항목

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

Microsoft Dynamics 365

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