다음을 통해 공유

HTTP 요청을 작성하고 포털 웹 API에 대한 오류 처리

  • 아티클

웹 API와의 상호 작용에는 필수 헤더로 HTTP 요청을 작성하고 오류를 포함한 HTTP 응답 처리가 포함됩니다.

중요

  • 이 기능이 작동하려면 포털 버전이 9.3.3.x 이상이어야 합니다.

웹 API URL 및 버전 관리

다음 표의 형식을 사용하여 웹 API URL을 구성합니다.

요소 Description
프로토콜 https://
기준 URL <포털 URL>
웹 API 경로 _api
리소스 사용할 테이블의 논리 이름

예를 들어, 케이스를 참조할 때 이 형식을 사용하십시오.

https://contoso.powerappsportals.com/_api/case

모든 웹 API 리소스는 웹 역할과 관련하여 각각의 테이블 권한을 따릅니다.

HTTP 메서드

HTTP 요청은 다른 종류의 메서드를 사용할 수 있습니다. 그러나 포털 웹 API는 다음 표의 메서드만 지원합니다.

Method 사용
이용 테이블에서 데이터를 검색할 때 사용합니다.
이후 레코드를 만들 때 사용합니다.
패치 테이블을 업데이트하거나 upsert 작업을 수행할 때 사용합니다.
Delete 레코드 또는 레코드의 개별 필드 값을 삭제할 때 사용합니다.
Put 제한된 상황에서 레코드의 개별 필드를 업데이트하는 데 사용합니다.

HTTP 헤더

웹 API는 JSON만 지원합니다. 각 HTTP 헤더에는 다음이 포함되어야 합니다.

  • application/json에 대한 Accept 헤더 값. 응답 본문이 예상되지 않는 경우에도 마찬가지입니다.
  • 요청에 요청 본문의 JSON 데이터가 포함된 경우 값이application/json인 Content-Type 헤더를 포함해야 합니다.

현재 OData 버전은 4.0이지만 향후 버전에서 새로운 기능이 포함될 수 있습니다. 다음 구문을 사용하여 향후 코드에 적용될 OData 버전에 대한 모호성이 없는지 확인하십시오.

구문

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

예: CSRF 토큰에 대한 래퍼 AJAX 함수

	(function(webapi, $){
		function safeAjax(ajaxOptions) {
			var deferredAjax = $.Deferred();
	
			shell.getTokenDeferred().done(function (token) {
				// add headers for ajax
				if (!ajaxOptions.headers) {
					$.extend(ajaxOptions, {
						headers: {
							"__RequestVerificationToken": token
						}
					}); 
				} else {
					ajaxOptions.headers["__RequestVerificationToken"] = token;
				}
				$.ajax(ajaxOptions)
					.done(function(data, textStatus, jqXHR) {
						validateLoginSession(data, textStatus, jqXHR, deferredAjax.resolve);
					}).fail(deferredAjax.reject); //ajax
			}).fail(function () {
				deferredAjax.rejectWith(this, arguments); // on token failure, pass the token ajax and args
			});
	
			return deferredAjax.promise();	
		}
		webapi.safeAjax = safeAjax;
})(window.webapi = window.webapi || {}, jQuery)

예: 테이블 데이터 검색

	webapi.safeAjax({
				type: "GET",
				url: "/_api/contacts?$select=firstname,lastname",
				contentType: "application/json",
				success: function (res) {
						console.log(res);
				}
	});

예: 테이블 데이터 만들기

	webapi.safeAjax({
		type: "POST",
		url: "/_api/accounts",
		contentType: "application/json",
		data: JSON.stringify({
			"name": "Sample Account"
		}),
		success: function (res, status, xhr) {
			console.log("entityID: "+ xhr.getResponseHeader("entityid"))
		}
	});

예: 테이블 데이터 업데이트

		webapi.safeAjax({
		type: "PATCH",
		url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
		contentType: "application/json",
		data: JSON.stringify({
			"name": "Sample Account - Updated"
		}),
		success: function (res) {
			console.log(res);
		}
	});

예: 테이블 데이터 삭제

		webapi.safeAjax({
		type: "DELETE",
		url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
		contentType: "application/json",
		success: function (res) {
			console.log(res);
		}
	});

상태 코드 식별

각 HTTP 요청 응답에는 상태 코드가 포함됩니다. 포털 웹 API에서 반환되는 상태 코드는 다음을 포함합니다.

코드 Description Type
200 확인 작업이 응답 본문에 데이터를 반환할 때 이 응답이 예상됩니다. 성공
204 콘텐츠 없음 작업이 성공하지만 응답 본문에 데이터를 반환하지 않을 때 이 응답이 예상됩니다. 성공
403 금지 다음 유형의 오류인 경우 이 응답이 예상됩니다.
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 클라이언트 오류
401 권한 없음 다음 유형의 오류인 경우 이 응답이 예상됩니다.
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 클라이언트 오류
413 페이로드가 너무 큼 요청 길이가 너무 길 때 이 응답이 예상됩니다. 클라이언트 오류
400 BadRequest 인수가 유효하지 않을 때 이 응답이 예상됩니다.
InvalidAttribute		 클라이언트 오류
404 찾을 수 없음 리소스가 존재하지 않을 때 이 응답이 예상됩니다.
테이블은 웹 API에 대해 노출되지 않습니다.		 클라이언트 오류
405 메서드가 허용되지 않음 이 오류는 잘못된 메서드 및 리소스 조합의 경우 발생합니다. 예를 들어, 테이블 컬렉션에서는 DELETE 또는 PATCH를 사용할 수 없습니다. 다음 유형의 오류인 경우 이 상황이 발생할 수 있습니다.
  • InvalidOperation
  • NotSupported
 클라이언트 오류
501 구현 안 됨 요청한 일부 작업이 구현되지 않을 때 이 응답이 예상됩니다. 서버 오류
503 서비스를 사용할 수 없음 웹 API 서비스를 사용할 수 없을 때 이 응답이 예상됩니다. 서버 오류

응답의 오류 구문 분석

여전히 내부 오류가 포함된 다음 HTTP 응답 예를 고려하세요.

{
  "error":{
    "code": "This code is not related to the http status code and is frequently empty",
    "message": "A message describing the error",
    "cdscode": "Dataverse error code",
    "innererror": {
        "code": "800xxxx",
        "message": "A message describing the error. This is frequently the same as the outer message.."
      }
    }
  }

오류 코드

처리된 모든 시나리오에 대해 오류 코드가 16진 형식으로 표시됩니다. 다음 표에는 각 오류 코드와 해당 이름 및 메시지가 나열되어 있습니다.

오류 코드 오류 이름 오류 메시지
900400FF NoAttributesForTableCreate 테이블 만들기 작업에 특성이 없습니다.
90040100 InvalidAttribute 테이블 {1}에 특성 {0}이(가) 없습니다.
90040101 AttributePermissionIsMissing 웹 API에 대해 엔터티 {1} 내의 특성 {0}이(가) 사용되지 않았습니다.
90040102 TablePermissionWriteIsMissingDuringUpdate {0} 엔터티를 업데이트할 수 있는 권한이 없습니다.
90040103 TablePermissionCreateIsMissing {0} 엔터티를 만들 수 있는 권한이 없습니다.
90040104 TablePermissionDeleteIsMissing {0) 엔터티를 삭제할 수 있는 권한이 없습니다.
90040105 TablePermissionAppendIsMissngDuringAssociationChange 테이블 {0}을(를) {1}과(와) 연결하거나 연결 해제할 수 있는 권한이 없습니다.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange 테이블 {1}을(를) {0}과(와) 연결하거나 연결 해제할 수 있는 권한 없음
90040107 HttpAntiForgeryException 위조 방지 쿠키 토큰과 양식 필드 토큰이 일치하지 않습니다.
90040109 MissingPortalSessionCookie 잘못된 세션 토큰이 throw 메서드로 전달되었습니다.
9004010C ResourceDoesNotExists 세그먼트 '{0}'에 리소스가 없습니다.
9004010D CDSError CDS 오류가 발생했습니다.

HTTP 상태 코드 500의 처리되지 않은 오류에 대한 응답이 "요청을 처리하는 중 예기치 않은 오류가 발생했습니다" 오류를 반환합니다.

참조 항목