다음을 통해 공유

웹 API 조건부 작업 샘플

  • 아티클

 

게시 날짜: 2017년 1월

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

이 그룹의 샘플은 Dynamics 365 서버에 포함된 및/또는 현재 클라이언트에서 보유하고 있는 엔터티 레코드의 버전에 따라 조건적으로 작업을 수행하는 방법을 보여줍니다. 자세한 내용은 웹 API를 사용하여 조건부 작업을 수행을 참조하십시오. 이 샘플은 다음 언어에 대해 별도 프로젝트로 구현됩니다.

웹 API 조건부 작업 샘플(C#)

웹 API 조건부 작업 샘플(클라이언트 쪽 JavaScript)

Dynamics 365 웹 API는 리소스 버전 컨트롤을 구현하기 위해 ETag를 사용하는 OData v4.0 프로토콜의 규칙을 따릅니다. 조건부 웹 API 작업은 버전 관리 메커니즘에 따라 다릅니다.

이 항목에서는 샘플의 구조와 내용을 높은 수준에서 중립적인 언어 수준으로 설명합니다. HTTP 요청 및 응답과 적용 가능한 경우 관련된 프로그램 출력을 설명합니다. 이 항목에 설명된 작업을 수행하는 방법에 대해 각 언어 관련 구현 및 관련 세부 정보는 위의 링크된 샘플 항목을 검토하십시오.

시연

이 샘플은 다음 테이블에 나열된 세 개의 주요 섹션으로 구분됩니다. 각 섹션은웹 API를 사용하여 조건부 작업을 수행 항목의 관련 개념 섹션에서 자세히 설명하는 일련의 관련 웹 API 작업을 포함합니다.

코드 섹션

관련 개념 항목

조건부 GET

조건부 검색

삭제 및 업데이트의 낙관적 동시 실행

낙관적 동시 실행 적용

upsert 작업 제어

upsert 작업 제한

다음 섹션에서는 수행되는 Dynamics 365 웹 API 작업과 각 언어 구현에 동일한 해당 HTTP 메시지 및 관련 콘솔 출력에 대한 간략한 설명을 담고 있습니다. 요약하자면, 덜 관련된 HTTP 헤더가 생략되었습니다. 레코드의 URI는 사용자 Dynamics 365 서버가 할당한 기본 조직 주소와 레코드 ID에 따라 다릅니다.

샘플 데이터

샘플은 사용자 코드 섹션을 실행하기 전에 다음과 같은 레코드를 만듭니다.

엔터티 유형

클라이언트 할당 속성

서버 할당 속성

account EntityType

이름: Contoso Ltd.
수익: 5000000
전화: 555-0000
설명: Parent company of Contoso Pharmaceuticals, etc.

ID:14e151db-9b4f-e611-80e0-00155da84c08
초기 ETag: W/"628448"

조건부 GET

이 프로그램 섹션에서는 클라이언트에 최신 레코드 상태를 유지하면서 네트워크 대역폭과 서버 처리를 최적화하기 위해 조건부 검색을 수행하는 방법을 보여줍니다.추가 정보:조건부 검색

  1. 거래처 레코드를 만들 때 반환된 초기 ETag 값으로 식별되는 현재 버전과 일치하지 않는 경우에만 거래처 Contoso Ltd. 검색을 시도하십시오. 이 조건은 If-None-Match 헤더에서 나타냅니다.

    HTTP 요청

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 응답

    HTTP/1.1 304 Not Modified

    콘솔 출력

    Instance retrieved using ETag: W/"628448"
Expected outcome: Entity was not modified so nothing was returned.

    응답 값 304 Not Modified는 현재 레코드가 가장 최근이며 서버가 응답 본문에서 요청한 레코드를 반환하지 않는다는 것을 나타냅니다.

  2. 기본 전화 번호 속성을 수정하여 거래처를 업데이트합니다.

    HTTP 요청

    PUT http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json
{
  "value": "555-0001"
}

    HTTP 응답

    HTTP/1.1 204 No Content

    콘솔 출력

    Account telephone number updated.

  3. 원본 ETag 값을 다시 사용하여 동일한 조건부 GET 작업을 다시 시도합니다. 이번에는 서버의 버전이 요청에서 식별된 버전과 다르기(최신) 때문에 작업이 요청된 데이터를 반환합니다. 모든 레코드 검색에서처럼 응답은 현재 버전을 식별하는 ETag 헤더를 포함합니다.

    HTTP 요청

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 응답

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628460"
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628460\"",
  "name":"Contoso Ltd",
  "revenue":5000000.0000,
  "telephone1":"555-0001",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    콘솔 출력

    Instance retrieved using ETag: W/"628448"
{
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628460\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0001",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

삭제 및 업데이트의 낙관적 동시 실행

이 프로그램 섹션에서는 조건부 삭제 및 업데이트 작업을 수행하는 방법을 보여줍니다. 이러한 작업은 가장 일반적으로 다중 사용자 환경에서 레코드 처리 방식에 대해 낙관적 동시성 실행을 구현하는 데에 사용됩니다.추가 정보:낙관적 동시 실행 적용

  1. 원래 거래처가 최초 버전(ETag 값)과 일치하는 경우에만 원래 거래처 삭제를 시도합니다. 이 조건은 If-Match 헤더에서 나타냅니다. 이전 섹션에서 거래처 레코드가 업데이트되었기 때문에 이 작업이 실패하며, 서버에서 이 버전이 업데이트되었습니다.

    HTTP 요청

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 응답

    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.", . . .
    }
}

    콘솔 출력

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not deleted using ETag 'W/"628448"', status code: '412'.

  2. 거래처가 ETag 값과 일치하는 경우에만 거래처 업데이트를 시도합니다. 이 조건은 If-Match 헤더에서 나타내며 같은 이유 때문에 작업이 실패합니다.

    HTTP 요청

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0002",
  "revenue": 6000000
}

    HTTP 응답

    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.", . . . 
  }
}

    콘솔 출력

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not updated using ETag 'W/"628448"', status code: '412'.

  3. 앞 섹션에서 마지막 레코드 검색에서 가져온 현재 ETag 값을 대신 사용하여 업데이트를 다시 시도합니다.

    HTTP 요청

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628460"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
  "telephone1": "555-0003",
  "revenue": 6000000
}

    HTTP 응답

    HTTP/1.1 204 No Content

    콘솔 출력

    Account successfully updated using ETag: W/"628460", status code: '204'.

  4. 현재 거래처 상태를 검색하고 출력하여 성공한 업데이트를 확인합니다. 이 작업은 기본 GET 요청을 사용합니다.

    HTTP 요청

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 응답

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628461"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628461\"",
  "name":"Contoso Ltd",
  "revenue":6000000.0000,
  "telephone1":"555-0003",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    콘솔 출력

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628461\"",
  "name": "Contoso Ltd",
  "revenue": 6000000.0,
  "telephone1": "555-0003",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

upsert 작업 제어

이 섹션 프로그램에서는 업데이트 작업만 또는 삽입 작업만을 수행하기 위해 upsert 작업을 제한하여 조건부 PATCH 작업을 수행하는 방법을 보여줍니다.추가 정보:upsert 작업 제한

  1. 업데이트하지 않고 이 거래처에 대한 기본 전화 및 수익 속성 삽입을 시도합니다.* 값이 있는 If-None-Match 헤더가 upsert 조건을 나타냅니다. (다른 사용자 또는 프로세스에 의해 동시에 삭제되지 않은 한)이 거래처 레코드가 서버에 남아있기 때문에 이 작업이 실패합니다.

    HTTP 요청

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-None-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0004",
  "revenue": 7500000
}

    HTTP 응답

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"A record with matching key values already exists.", . . .
  }
}

    콘솔 출력

    Expected Error: A record with matching key values already exists.
        Account not updated using ETag 'W/"628448", status code: '412'.

  2. 생성하지 않고 동일한 업데이트 작업 수행을 시도합니다. 이를 완료하려면 * 값이 있는 조건부 If-Match 헤더를 사용해야 합니다. 서버에 레코드가 존재하기 때문에 이 작업은 성공합니다.

    HTTP 요청

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0005",
  "revenue": 7500000
}

    HTTP 응답

    HTTP/1.1 204 No Content

    콘솔 출력

    Account updated using If-Match '*'

  3. 기본 GET 요청으로 현재 거래처 상태를 검색하고 출력합니다. 반환된 ETag 값은 새로운 업데이트된 거래처 레코드 버전을 반영하도록 변경되었습니다.

    HTTP 요청

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 응답

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628463"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628463\"",
  "name":"Contoso Ltd","revenue":7500000.0000,
  "telephone1":"555-0005",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    콘솔 출력

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628463\"",
  "name": "Contoso Ltd",
  "revenue": 7500000.0,
  "telephone1": "555-0005",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

  4. 기본 DELETE로 거래처를 삭제합니다.

    HTTP 요청

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 응답

    HTTP/1.1 204 No Content

    콘솔 출력

    Account was deleted.

  5. 2단계에서와 마찬가지로 거래처가 존재하는 경우 거래처 업데이트를 시도합니다. 다시 말하지만 이 조건은 * 값이 있는 If-Match 헤더에서 나타냅니다. 이 레코드가 방금 삭제되었기 때문에 이 작업이 실패합니다. 그러나 이 If-Match 헤더가 없다면 기본 upsert 작업으로 성공적으로 새 레코드가 만들어질 것입니다.

    HTTP 요청

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0006",
  "revenue": 7500000
}

    HTTP 응답

    HTTP/1.1 404 Not Found
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"account With Id = 14e151db-9b4f-e611-80e0-00155da84c08 Does Not Exist", . . .
  }
}

    콘솔 출력

    Expected Error: Account with Id = 14e151db-9b4f-e611-80e0-00155da84c08 does not exist.
Account not updated because it does not exist, status code: '404'.

4단계에서 거래처 레코드를 이미 삭제했기 때문에 샘플 데이터를 정리하지 않아도 됩니다.

참고 항목

Microsoft Dynamics 365 웹 API 사용
웹 API를 사용하여 조건부 작업을 수행
웹 API 조건부 작업 샘플(C#)
웹 API 조건부 작업 샘플(클라이언트 쪽 JavaScript)

Microsoft Dynamics 365

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