포털 웹 API 개요
포털 웹 API는 Power Pages 사이트 내에서 더 풍부한 사용자 경험을 가능하게 합니다. 포털 웹 API를 사용하여 웹 페이지의 모든 Microsoft Dataverse 테이블에 걸쳐 생성, 읽기, 업데이트 및 삭제 작업을 수행할 수 있습니다. 예를 들어 포털 웹 API를 사용하여 양식 또는 다단계 양식을 사용하지 않고 새 계정을 만들고 연락처를 업데이트할 수 있습니다.
중요
- 이 기능이 작동하려면 Power Pages 사이트 버전이 9.3.3.x 이상이어야 합니다.
- 포털 웹 API는 포털 페이지 안에서 더 풍부한 사용자 환경을 만들기 위해 구축되었습니다. 타사 서비스 또는 애플리케이션 통합에는 최적화되어 있지 않습니다. 포털 웹 API를 사용하여 다른 Power Pages 사이트와 통합하는 것도 지원되지 않습니다.
- 포털 웹 API 작업은 데이터와 관련된 테이블(예: 거래처, 연락처 또는 사용자 지정 테이블)로 제한됩니다. 테이블 메타 데이터 또는 포털 구성 테이블 데이터 구성(예: adx_contentsnippet, adx_entityform 또는 adx_entitylist와 같은 포털 테이블 구성)은 포털 웹 API에서는 지원되지 않습니다. 전체 목록을 보려면 이 토픽 후반의 지원되지 않는 구성 테이블로 이동하세요.
- 포털 웹 API는 서버 측 캐싱의 이점을 누리므로 웹 API에 대한 후속 호출은 초기 호출보다 빠릅니다. 포털 서버 측 캐시를 지우면 일시적인 성능 저하가 발생합니다.
- 포털 웹 API 작업에는 Power Pages 라이선스가 필요합니다. 예를 들어 익명 사용자가 만든 Web API 호출은 익명 사용자 용량에 포함됩니다. 인증된 사용자(내부 또는 외부)가 인증한 웹 API 호출은 페이지 보기에 포함되지 않지만 적용 가능한 인증 사용자 용량 라이선스가 필요합니다. 추가 정보: Power Pages 라이선싱 FAQ
웹 API 작업
포털 웹 API는 Dataverse를 사용하여 수행할 수 있는 Dataverse 작업에 대한 기능의 하위 집합을 제공합니다. 학습 곡선을 줄이기 위해 API 형식을 최대한 유사하게 유지했습니다.
노트
Web API 작업은 대소문자를 구분합니다.
Power Pages에서 사용 가능한 웹 API 작업
웹 API의 사이트 설정
포털에서 포털 웹 API를 사용하려면 사이트 설정을 활성화해야 합니다. 포털 웹 API로 수정할 수 있거나 수정할 수 없는 테이블 필드를 결정하는 필드 수준 웹 API를 구성할 수도 있습니다.
노트
이러한 설정에 대해 논리적 이름 테이블을 사용하십시오(예:거래처).
| 사이트 설정 이름 | 설명 |
|---|---|
| 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을 확인할 수 있습니다.
측면 패널에서 Dataverse 탭을 선택하고 테이블을 선택합니다.
...(명령 옵션)을 선택한 다음 고급, 도구 및 세트 이름 복사를 선택하여 테이블의 EntitySetName을 클립보드에 복사합니다.
개인 정보 보호법 및 규정
모든 요청 헤더에는 감사 목적으로 전달된 연락처 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
알려진 문제점
상위, 연락처 또는 거래처 범위가 쿼리에 조건을 추가할 때 사용자가 여러 수준의 일대다 또는 다대다테이블 권한이 있는 테이블에 대해 GET Web API 요청을 호출하면 CDS 오류가 발생합니다.
이 문제를 해결하려면 OData 쿼리에서 FetchXML을 사용하는 것이 좋습니다.
또는 사이트 설정 Webapi/<table name>/disableodatafilter를 True로 지정합니다.
중요
사이트 설정 Webapi/<table name>/disableodatafilter를 True로 변경하면 Web API GET 호출의 성능이 느려질 수 있습니다.
사이트 설정은 포털 버전 9.4.10.74 이상에서 사용할 수 있습니다.