HTTP 요청을 작성하고 포털 웹 API에 대한 오류 처리
참고
2022년 10월 12일부터 Power Apps 포털이 Power Pages가 됩니다. 추가 정보: Microsoft Power Pages는 이제 일반적으로 사용할 수 있습니다(블로그)
곧 Power Apps 포털 설명서를 마이그레이션하고 Power Pages 설명서와 병합할 예정입니다.
웹 API와의 상호 작용에는 필수 헤더로 HTTP 요청을 작성하고 오류를 포함한 HTTP 응답 처리가 포함됩니다.
중요
- 이 기능이 작동하려면 포털 버전이 9.3.3.x 이상이어야 합니다.
웹 API URL 및 버전 관리
다음 표의 형식을 사용하여 웹 API URL을 구성합니다.
| 요소 | Description |
|---|---|
| 프로토콜 | https:// |
| 기준 URL | <portal URL> |
| 웹 API 경로 | _api |
| 리소스 | 사용할 테이블의 논리 이름 |
예를 들어, 케이스를 참조할 때 이 형식을 사용하십시오.
https://contoso.powerappsportals.com/_api/case
모든 웹 API 리소스는 웹 역할과 관련하여 각각의 포털 테이블 권한을 따릅니다.
HTTP 메서드
HTTP 요청은 다른 종류의 메서드를 사용할 수 있습니다. 그러나 포털 웹 API는 다음 표의 메서드만 지원합니다.
| Method | 사용 |
|---|---|
| 이용 | 테이블에서 데이터를 검색할 때 사용합니다. |
| 이후 | 레코드를 만들 때 사용합니다. |
| 패치 | 테이블을 업데이트하거나 upsert 작업을 수행할 때 사용합니다. |
| Delete | 레코드 또는 레코드의 개별 필드 값을 삭제할 때 사용합니다. |
| Put | 제한된 상황에서 레코드의 개별 필드를 업데이트하는 데 사용합니다. |
HTTP 헤더
웹 API는 JSON만 지원합니다. 각 HTTP 헤더에는 다음이 포함되어야 합니다.
- 응답 본문이 예상되지 않는 경우에도 마찬가지인 application/json에 대한 수락 헤더 값입니다.
- 요청에 요청 본문의 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 금지 | 다음 유형의 오류인 경우 이 응답이 예상됩니다.
|
클라이언트 오류 |
| 401 권한 없음 | 다음 유형의 오류인 경우 이 응답이 예상됩니다.
|
클라이언트 오류 |
| 413 페이로드가 너무 큼 | 요청 길이가 너무 길 때 이 응답이 예상됩니다. | 클라이언트 오류 |
| 400 BadRequest | 인수가 유효하지 않을 때 이 응답이 예상됩니다. InvalidAttribute |
클라이언트 오류 |
| 404 찾을 수 없음 | 리소스가 존재하지 않을 때 이 응답이 예상됩니다. 테이블은 웹 API에 대해 노출되지 않습니다. |
클라이언트 오류 |
| 405 메서드가 허용되지 않음 | 이 오류는 잘못된 메서드 및 리소스 조합의 경우 발생합니다. 예를 들어, 테이블 컬렉션에서는 DELETE 또는 PATCH를 사용할 수 없습니다. 다음 유형의 오류인 경우 이 상황이 발생할 수 있습니다.
|
클라이언트 오류 |
| 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의 처리되지 않은 오류에 대한 응답이 "요청을 처리하는 중 예기치 않은 오류가 발생했습니다" 오류를 반환합니다.
참고 항목:
포털 웹 API 개요
포털은 웹 API를 사용하여 작업을 쓰고 업데이트하고 삭제합니다.
포털은 웹 API를 사용하여 작업을 읽습니다.
참고
귀사의 설명서 언어 기본 설정에 대해 말씀해 주시겠습니까? 간단한 설문 조사에 응해주세요. (이 설문 조사는 영어로 되어 있습니다.)
이 설문 조사는 약 7분 정도 걸립니다. 개인 데이터는 수집되지 않습니다(개인정보처리방침).