포털 웹 API 개요

참고

2022년 10월 12일부터 Power Apps 포털이 Power Pages가 됩니다. 추가 정보: Microsoft Power Pages는 이제 일반적으로 사용할 수 있습니다(블로그)
곧 Power Apps 포털 설명서를 마이그레이션하고 Power Pages 설명서와 병합할 예정입니다.

포털 웹 API는 Power Apps 포털 페이지 내에서 더 풍부한 사용자 경험을 가능하게 합니다. 포털 웹 API를 사용하여 포털 페이지의 모든 Microsoft Dataverse 테이블에 걸쳐 생성, 읽기, 업데이트 및 삭제 작업을 수행할 수 있습니다. 예를 들어 포털 관리 앱 대신 포털 웹 API를 사용하여 새 계정을 만들거나 연락처를 업데이트하거나 제품에 대해 테이블 권한을 변경할 수 있습니다.

참고

Power Pages에서 포털 웹 API를 사용할 수도 있습니다. 추가 정보: Power Pages란

중요

• 이 기능이 작동하려면 포털 버전이 9.3.3.x 이상이어야 합니다.
• 포털 웹 API는 포털 페이지 안에서 더 풍부한 사용자 환경을 만들기 위해 구축되었습니다. 타사 서비스 또는 애플리케이션 통합에는 최적화되어 있지 않습니다. 포털 웹 API를 사용하여 다른 Power Apps 포털 사이트와 통합하는 것도 지원되지 않습니다.
• 포털 웹 API 작업은 데이터와 관련된 테이블로 제한됩니다—예를 들어 계정, 연락처 또는 사용자 정의 테이블이 있습니다. 테이블 메타 데이터 또는 포털 구성 테이블 데이터 구성—예를 들어 adx_contentsnippet, adx_entityform 또는 adx_entitylist와 같은 포털 테이블 구성—은 포털 웹 API에서는 지원되지 않습니다. 전체 목록을 보려면 이 토픽 후반의 지원되지 않는 구성 테이블로 이동하세요.
• 포털 웹 API는 서버 측 캐싱의 이점을 누리므로 웹 API에 대한 후속 호출은 초기 호출보다 빠릅니다. 포털 서버 측 캐시를 지우면 일시적인 성능 저하가 발생합니다.
• 포털 웹 API 작업에는 Power Apps 포털 라이선스가 필요합니다. 예를 들어 익명 사용자가 만든 웹 API 호출은 페이지 보기 용량에 포함됩니다. 인증된 사용자(내부 또는 외부)가 인증한 웹 API 호출은 페이지 보기에 포함되지 않지만 적용 가능한 라이선스가 필요합니다. 추가 정보: Power Apps 포털 라이선스 FAQ

웹 API 작업

포털 웹 API는 Dataverse를 사용하여 수행할 수 있는 Dataverse 작업에 대한 기능의 하위 집합을 제공합니다. 학습 곡선을 줄이기 위해 API 형식을 최대한 유사하게 유지했습니다.

참고

Web API 작업은 대소문자를 구분합니다.

포털에서 사용 가능한 웹 API 작업

• 테이블에서 레코드 읽기
• 테이블에 레코드 만들기
• 테이블의 레코드 업데이트 및 삭제
• 테이블 연결 및 분리

참고

포털 웹 API를 사용하여 작업 및 기능을 호출하는 것은 지원되지 않습니다.

웹 API의 사이트 설정

포털에서 포털 웹 API를 사용하려면 사이트 설정을 활성화해야 합니다. 포털 웹 API로 수정할 수 있거나 수정할 수 없는 테이블 필드를 결정하는 필드 수준 웹 API를 구성할 수도 있습니다.

참고

이러한 설정에 대해 논리적 이름 테이블을 사용하십시오(예:거래처).

사이트 설정 이름	Description
Webapi/<table name>/enabled	<table name>에 대한 웹 API를 활성화하거나 비활성화합니다. 기본값: False 유효한 값: True, False
Webapi/<table name>/fields	웹 API로 수정할 수 있는 쉼표로 구분된 속성 목록을 정의합니다. 가능한 값: - 모든 특성: * - 특정 특성: attr1,attr2,attr3 메모: 값은 별표(*) 또는 쉼표로 구분된 필드 이름 목록 중 하나여야 합니다. 중요: 필수 사이트 설정입니다. 이 설정이 없으면 "이 엔터티에 대해 정의된 필드가 없습니다."라는 오류가 표시됩니다.
Webapi/error/innererror	InnerError를 활성화 또는 비활성화합니다. 기본값: False 유효한 값: True, False
Webapi/<table name>/disableodatafilter	OData 필터를 활성화하거나 비활성화합니다. 기본값: False 유효한 값: True, False 자세한 내용은 알려진 문제를 참조하세요. 사이트 설정은 포털 버전 9.4.10.74 이상에서 사용할 수 있습니다.

참고

사이트 설정 변경 사항을 적용하려면 활성으로 설정해야 합니다.

예를 들어 인증된 사용자가 이 엔터티에 대해 생성, 업데이트 및 삭제 작업을 수행할 수 있는 서비스 사례 테이블에 대한 웹 API를 노출하기 위해 사이트 설정이 다음 표에 나와 있습니다.

사이트 설정 이름	사이트 설정 값
Webapi/incident/enabled	참
Webapi/incident/fields	attr1, attr2, attr3

포털 웹 API를 통한 보안

테이블 권한을 사용하여 포털의 개별 레코드에 대한 레코드 기반 보안을 구성할 수 있습니다. 포털 웹 API는 테이블(엔터티) 레코드에 액세스하고 연결된 웹 역할을 통해 사용자에게 부여된 테이블 권한을 따릅니다.

열 권한을 구성하여 포털 웹 API를 사용하는 동안 테이블 내의 개별 열에 대한 권한을 추가로 정의할 수 있습니다.

포털 웹 API 요청 인증

인증 및 권한 부여는 애플리케이션 세션에서 관리하기 때문에 인증 코드를 포함할 필요가 없습니다. 모든 웹 API 호출에는 CSRF(교차 사이트 요청 위조) 토큰이 포함되어야 합니다.

EntitySetName 사용

코드에서 포털 웹 API를 사용하여 Dataverse 테이블을 참조할 때 EntitySetName을 사용해야 합니다. 예를 들어 거래처 테이블에 액세스하려면 코드 구문에서 거래처의 EntitySetName; /_api/accounts()를 사용합니다.

참고

사이트 설정에 테이블 논리 이름을 사용합니다(예:거래처).

다음 단계에 따라 특정 테이블의 EntitySetName을 확인할 수 있습니다.

1. https://make.powerapps.com로 이동

2. 측면 패널에서 Dataverse 탭을 선택하고 테이블을 선택합니다.

3. ...(명령 옵션)을 선택한 다음 고급, 도구 및 세트 이름 복사를 선택하여 테이블의 EntitySetName을 클립보드에 복사합니다.

   

일반 데이터 보호 규정(GDPR)

모든 요청 헤더에는 감사 목적으로 전달된 연락처 ID가 있습니다. 익명 사용자의 경우 null로 전달됩니다.

감사 로깅이 활성화된 경우 사용자는 Office 365 감사 로그에서 모든 감사 이벤트를 볼 수 있습니다.

추가 정보:
활동 로깅 활성화 및 사용하기
감사 로그 레코드 내보내기, 구성 및 보기

지원되지 않는 구성 테이블

다음 구성 테이블에는 포털 웹 API를 사용할 수 없습니다.

adx_contentaccesslevel

adx_contentsnippet

adx_entityform

adx_entityformmetadata

adx_entitylist

adx_entitypermission

adx_entitypermission_webrole

adx_externalidentity

adx_pagealert

adx_pagenotification

adx_pagetag

adx_pagetag_webpage

adx_pagetemplate

adx_portallanguage

adx_publishingstate

adx_publishingstatetransitionrule

adx_publishingstatetransitionrule_webrole

adx_redirect

adx_setting

adx_shortcut

adx_sitemarker

adx_sitesetting

adx_urlhistory

adx_webfile

adx_webfilelog

adx_webform

adx_webformmetadata

adx_webformsession

adx_webformstep

adx_weblink

adx_weblinkset

adx_webnotificationentity

adx_webnotificationurl

adx_webpage

adx_webpage_tag

adx_webpageaccesscontrolrule

adx_webpageaccesscontrolrule_webrole

adx_webpagehistory

adx_webpagelog

adx_webrole_systemuser

adx_website

adx_website_list

adx_website_sponsor

adx_websiteaccess

adx_websiteaccess_webrole

adx_websitebinding

adx_websitelanguage

adx_webtemplate

알려진 문제점

부모 범위가 정의된 여러 수준의 1대다 또는 다대다 테이블 권한이 있는 테이블에 대해 GET 웹 API 요청을 호출하면 사용자가 CDS 오류를 받게 됩니다.

이 문제를 해결하려면 OData 쿼리에서 FetchXML을 사용하는 것이 좋습니다.

또는 사이트 설정 Webapi/<table name>/disableodatafilter를 True로 지정합니다.

중요

사이트 설정 Webapi/<table name>/disableodatafilter를 True로 변경하면 Web API GET 호출의 성능이 느려질 수 있습니다.

사이트 설정은 포털 버전 9.4.10.74 이상에서 사용할 수 있습니다.

다음 단계

포털 웹 API를 사용하여 데이터 쿼리

참조 항목

HTTP 요청 작성 및 오류 처리
포털은 웹 API를 사용하여 작업을 쓰고 업데이트하고 삭제합니다.
자습서: 포털 웹 API 사용

참고

귀사의 설명서 언어 기본 설정에 대해 말씀해 주시겠습니까? 간단한 설문 조사에 응해주세요. (이 설문 조사는 영어로 되어 있습니다.)

이 설문 조사는 약 7분 정도 걸립니다. 개인 데이터는 수집되지 않습니다(개인정보처리방침).