HTTP 요청 및 처리 오류 작성

  • 아티클

 

게시 날짜: 2017년 1월

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

HTTP 요청을 작성하고 보내 웹 API와 상호 작용합니다. 적절한 HTTP 헤더를 설정하고 응답에 포함된 오류를 처리하는 방법을 알고 있어야 합니다.

이 항목의 내용

웹 API URL 및 버전

HTTP 메서드

HTTP 헤더

상태 코드 식별

응답의 오류 구문 분석

웹 API URL 및 버전

웹 API에 액세스하려면 다음 표의 구성 요소를 사용하여 URL을 작성해야 합니다.

항목

설명

프로토콜

적절한 프로토콜 https:// 또는 http://입니다.

기본 URL

이 URL은 일반적으로 웹 응용 프로그램을 여는 데 사용됩니다.

  • Microsoft Dynamics 365(온라인)의 경우 <tenant name>.crm.dynamics.com을 사용합니다.

  • 인터넷 연결 배포(IFD)의 경우 인스턴스에 대해 적절한 URL을 사용합니다. 이는 <organization name>.<domain name>입니다.

  • Dynamics 365(온-프레미스)의 경우 <server name>/<organization name>를 사용합니다.

웹 API 경로

웹 API의 경로는 /api/data/입니다.

버전

버전은 v[Major_version].[Minor_version][PatchVersion]/으로 나타냅니다. 이 릴리스에 대한 유효한 버전은 다음과 같습니다.

  • Microsoft Dynamics CRM Online 2016 업데이트 0.1 및 Microsoft Dynamics CRM 2016 업데이트 0.1의 경우 v8.0/

  • Microsoft Dynamics CRM Online 2016 업데이트 1 및 Microsoft Dynamics CRM 2016 서비스 팩 1의 경우 v8.1/

  • Dynamics 365용 2016년 12월 업데이트(온라인 및 온-프레미스)용 v8.2/

해당 업데이트나 서비스 팩을 적용한 경우 사용자가 사용하는 특정 값은 이 릴리스에서는 중요하지 않습니다. 추가 정보: 버전 호환성

리소스

사용하려는 엔터티, 함수 또는 작업의 이름입니다.

사용할 URL은 프로토콜 + 기본 URL + 웹 API 경로 + 버전 + 리소스로 구성됩니다.

버전 호환성

이 릴리스에서는 각 업데이트 또는 서비스 팩과 함께 여러 가지 부가적인 변경 사항을 적용했습니다. 이러한 업데이트가 적용되면 후속 보조 버전에 동일한 기능이 추가됩니다. 이 때문에 버전 8.2를 사용할 수 있으면 버전 8.1과 8.0은 동일한 기능을 갖게 됩니다. 이는 모든 변경 내용이 추가 내용 또는 Microsoft Dynamics 365웹 API 제한 사항에 나열된 항목을 다루는 버그 수정이기 때문에 가능합니다. 주요 변경 내용은 도입되지 않았습니다.

참고

다음 주 버전(v9)은 해당 버전을 사용하여 사용할 수 있는 기능을 도입합니다. 이후 보조 버전은 이전 보조 버전에 다시 포팅되지 않는 추가 기능을 제공할 수 있습니다. 사용자가 사용하는 URL에서 v8.2를 참조하면 v8.x용으로 작성된 코드가 v9.x에서 계속 작동합니다.

v8.x 릴리스의 경우 사용할 수 있는 최신 버전을 사용하고 이 주 버전 내의 업데이트나 서비스 팩에서 주요 변경 내용을 도입하지 않을 수 있습니다. 그러나 이는 향후 릴리스에서 다를 수 있기 때문에 사용자가 사용하는 서비스의 버전에 더 많은 관심을 기울여야 합니다.

HTTP 메서드

HTTP 요청은 다양한 메서드를 적용할 수 있습니다. 웹 API를 사용할 때 다음 표에 나열된 메서드만 사용합니다.

방법

사용법

GET

함수 호출을 포함하여 데이터를 검색할 때 사용합니다. 성공적인 검색에 예상되는 상태 코드는 200 OK입니다.

POST

엔터티를 만들거나 작업을 호출할 때 사용합니다.

PATCH

엔터티를 업데이트하거나 upsert 연산을 수행할 때 사용합니다.

DELETE

엔터티 또는 엔터티의 개별 속성을 삭제할 때 사용합니다.

PUT

제한된 상황에서 엔터티의 개별 속성을 업데이트하는 데 사용합니다. 대부분의 엔터티를 업데이트할 때 이 메서드는 권장되지 않습니다. 모델 엔터티를 업데이트할 때 사용합니다.

HTTP 헤더

OData 프로토콜은 JSON 및 ATOM 형식을 모두 사용할 수 있지만 웹 API는 JSON만 지원합니다. 따라서 다음 헤더를 적용할 수 있습니다.

모든 요청은 응답 본문이 예상되지 않을 때도 application/json의 Accept 헤더 값을 포함해야 합니다. 응답에서 반환되는 오류는 JSON로 반환됩니다. 코드는 이 헤더가 없어도 작동하지만 될 수 있으면 포함하는 것이 좋습니다.

현재 OData 버전은 4.0이지만 향후 버전에서 새로운 기능이 포함될 수 있습니다. 향후 어느 시점에 적용될 OData 버전에 대한 모호성이 없도록 하려면 항상 현재 OData 버전과 코드에 적용할 최대 버전에 대한 명시적인 표현을 포함해야 합니다.OData-Version 및 OData-MaxVersion 헤더를 모두 사용하여 값을 4.0으로 설정합니다.

모든 HTTP 헤더는 최소 다음 헤더를 포함해야 합니다.

Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0

요청 본문에 JSON 데이터를 포함하는 모든 요청은 값이 application/json인 Content-Type 헤더를 포함해야 합니다.

Content-Type: application/json

특정 기능을 사용하기 위해 추가 헤더를 사용할 수 있습니다.

  • 엔터티에 대한 만들기(POST) 또는 업데이트(PATCH) 작업에 대한 데이터를 반환하려면 return=representation 선호 설정을 포함합니다. 이 선호 설정이 POST 요청에 적용되면 성공적인 응답 상태는 201 (Created)입니다.PATCH 요청에 대해 성공적인 응답은 200 (OK) 상태를 갖게 됩니다. 이 선호 설정이 적용되지 않으면 두 작업 모두에서 기본적으로 응답의 본문에 반환되는 데이터가 없음을 나타내는 상태 204 (No Content)를 반환합니다.

    참고

    이 기능은 Dynamics 365용 2016년 12월 업데이트(온라인 및 온-프레미스)에서 추가되었습니다.

  • 쿼리에 서식이 있는 값을 반환하려면 Prefer 헤더를 사용하여 Microsoft.Dynamics.CRM.formattedvalue로 설정된 odata.include-annotations 기본 설정을 포함합니다.추가 정보:형식이 지정된 값 포함

  • 또한 odata.maxpagesize 옵션이 있는 Prefer 헤더를 사용하여 반환하려는 페이지 수를 지정합니다.추가 정보:페이지에 반환할 엔터티 수를 지정합니다.

  • 호출자가 가장할 권한이 있을 때 다른 사용자를 가장하려면 가장할 사용자의 값이 systemuserid인 MSCRMCallerID 헤더를 추가합니다.추가 정보:웹 API를 사용하여 다른 사용자를 가장.

  • 낙관적 동시 실행을 적용하려면 Etag 값을 가지고 있는 If-Match 헤더를 적용할 수 있습니다.추가 정보:낙관적 동시 실행 적용

  • POST 요청에 대해 중복 검색을 사용하도록 설정하려면 MSCRM.SuppressDuplicateDetection: false 헤더를 사용하면 됩니다.추가 정보:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

  • upsert 작업이 실제로 엔터티를 만들거나 업데이트해야 하는지를 제어하려면 If-Match 및 If-None-Match 헤더를 사용할 수도 있습니다.추가 정보:엔터티 Upsert.

  • 일괄 작업을 실행할 때 요청에 여러 가지 헤더 및 본문에 보내는 각 부분을 적용해야 합니다.추가 정보:웹 API를 사용하여 일괄 작업 실행.

상태 코드 식별

http 요청이 성공 또는 실패하든 응답은 상태 코드를 포함합니다.Microsoft Dynamics 365 웹 API에서 반환되는 상태 코드는 다음을 포함합니다.

코드

설명

유형

200 OK

작업이 응답 본문에 데이터를 반환할 때 예상됩니다.

성공

201 Created

엔터티가 POST 작업이 성공하고 요청에서 return-representation 선호 설정을 지정했을 때 예상됩니다.

참고

이 기능은 Dynamics 365용 2016년 12월 업데이트(온라인 및 온-프레미스)에서 추가되었습니다.

성공

204 No Content

작업이 성공하지만 응답 본문에 데이터를 반환하지 않을 때 예상됩니다.

성공

304 Not Modified

엔터티가 마지막 검색된 이후로 수정되었는지 테스트할 때 예상됩니다.추가 정보:조건부 검색

리디렉션

403 Forbidden

다음 유형의 오류인 경우 예상됩니다.

  • AccessDenied

  • AttributePermissionReadIsMissing

  • AttributePermissionUpdateIsMissingDuringUpdate

  • AttributePrivilegeCreateIsMissing

  • CannotActOnBehalfOfAnotherUser

  • CannotAddOrActonBehalfAnotherUserPrivilege

  • CrmSecurityError

  • InvalidAccessRights

  • PrincipalPrivilegeDenied

  • PrivilegeCreateIsDisabledForOrganization

  • PrivilegeDenied

  • unManagedinvalidprincipal

  • unManagedinvalidprivilegeedepth

클라이언트 오류

401 Unauthorized

다음 유형의 오류인 경우 예상됩니다.

  • BadAuthTicket

  • ExpiredAuthTicket

  • InsufficientAuthTicket

  • InvalidAuthTicket

  • InvalidUserAuth

  • MissingCrmAuthenticationToken

  • MissingCrmAuthenticationTokenOrganizationName

  • RequestIsNotAuthenticated

  • TamperedAuthTicket

  • UnauthorizedAccess

  • UnManagedInvalidSecurityPrincipal

클라이언트 오류

413 Payload Too Large

요청 길이가 너무 길 때 예상됩니다.

클라이언트 오류

400 BadRequest

인수가 유효하지 않을 때 예상됩니다.

클라이언트 오류

404 Not Found

리소스가 존재하지 않을 때 예상됩니다.

클라이언트 오류

405 Method Not Allowed

이 오류는 잘못된 메서드 및 리소스 조합의 경우 발생합니다. 예를 들어, 엔터티 컬렉션에서는 DELETE 또는 PATCH를 사용할 수 없습니다.

다음 유형의 오류인 경우 예상됩니다.

  • CannotDeleteDueToAssociation

  • InvalidOperation

  • NotSupported

클라이언트 오류

412 Precondition Failed

다음 유형의 오류인 경우 예상됩니다.

  • ConcurrencyVersionMismatch

  • DuplicateRecord

클라이언트 오류

500 Internal Server Error

엔터티를 만드는 POST 요청에서 중복 검색을 사용하고 만들 엔터티가 중복되는 경우 이를 예상할 수 있습니다.추가 정보:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

서버 오류

501 Not Implemented

요청한 일부 작업이 구현되지 않을 때 예상됩니다.

서버 오류

503 Service Unavailable

웹 API 서비스를 사용할 수 없을 때 예상됩니다.

서버 오류

응답의 오류 구문 분석

오류에 대한 자세한 내용은 응답에 JSON으로 포함됩니다. 오류의 형식은 다음과 같습니다.

{ "error":{ "code": "
        <This code is not related to the http status code and is frequently empty>", "message": "
        <A message describing the error>", "innererror": { "message": "
        <A message describing the error, this is frequently the same as the outer message>", "type": "Microsoft.Crm.CrmHttpException", "stacktrace": "
        <Details from the server about where the error occurred>" } } }

참고 항목

웹 API를 사용하여 작업 수행
웹 API를 사용하여 데이터 쿼리
웹 API를 사용하여 엔터티 만들기
웹 API를 사용하여 엔터티 검색
웹 API를 사용하여 엔터티 업데이트 및 삭제
웹 API를 사용하여 엔터티 연결 및 연결 해제
웹 API 기능 사용
웹 API 작업 사용
웹 API를 사용하여 일괄 작업 실행
웹 API를 사용하여 다른 사용자를 가장
웹 API를 사용하여 조건부 작업을 수행

Microsoft Dynamics 365

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