포털 웹 API를 사용하여 데이터 쿼리
Power Pages에서 사용 가능한 웹 API 작업을 사용할 수 있습니다. 웹 API 작업은 HTTP 요청 및 응답으로 구성됩니다. 이 문서에서는 HTTP 요청에서 사용할 수 있는 샘플 읽기 작업, 메서드, URI 및 샘플 JSON을 제공합니다.
전제 조건
웹 사이트 버전은 9.4.1.x 이상이어야 합니다.
웹 API 작업을 위한 테이블 및 필드를 활성화합니다. 추가 정보: 웹 API에 대한 사이트 설정
포털 웹 API는 테이블 레코드에 액세스하고 연결된 웹 역할을 통해 사용자에게 부여된 테이블 권한을 따릅니다. 올바른 테이블 권한을 구성했는지 확인하세요. 추가 정보: 웹 역할 만들기
노트
포털 웹 API를 사용하여 Dataverse 테이블을 참조할 때 EntitySetName을 사용해야 합니다. 예를 들어 account 테이블에 액세스하려면 코드 구문이 accounts의 EntitySetName을 사용합니다.
레코드 쿼리
다음 예에서는 계정 레코드를 쿼리합니다.
| 작업 | Method | URI |
|---|---|---|
| 테이블 레코드 검색 | 가져오기 |
[Portal URI]/_api/accounts
예제: https://contoso.powerappsportals.com/_api/accounts |
샘플 응답
{
"value": [
{
"@odata.etag": "W/\"1066412\"",
"name": "Fourth Coffee (sample)",
"accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
},
{
"@odata.etag": "W/\"1066413\"",
"name": "Litware, Inc. (sample)",
"accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
}
]
}
$select와 $top 시스템 쿼리 옵션을 사용하여 처음 세 계정에 대한 이름 속성을 반환합니다.
| 작업 | Method | URI |
|---|---|---|
| 처음 3개의 엔터티 레코드 검색 | 가져오기 |
[Portal URI]/_api/accounts?$select=name,revenue&$top=3
예제: https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3 |
계정 ID를 사용하여 계정 검색:
| 작업 | Method | URI |
|---|---|---|
| 레코드의 특정 속성 검색 | 가져오기 |
[Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name
예제: https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name |
샘플 응답
{
"@odata.etag": "W/\"1066414\"",
"name": "Adventure Works (sample)",
"accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}
시스템 쿼리 옵션 적용
엔터티 집합의 URL에 추가하는 각 시스템 쿼리 옵션은 쿼리 문자열 구문을 사용하여 추가됩니다. 첫 번째는 [?] 뒤에 추가되며 다음 쿼리 옵션은 [&]를 사용하여 구분됩니다. 모든 쿼리 옵션은 다음 예와 같이 대소문자를 구분합니다.
| Method | URI |
|---|---|
| 가져오기 |
[Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3
예제: https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3 |
요청별 속성
$select 시스템 쿼리 옵션을 사용하여 다음 예와 같이 반환되는 속성을 제한합니다.
| Method | URI |
|---|---|
| 가져오기 |
[Portal URI]/_api/accounts?$select=name,revenue&$top=3
예제: https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3 |
중요
성능 모범 사례입니다. 속성이 지정되지 않고 Webapi/<table name>/fields 사이트 설정 값을 *로 구성한 경우 모든 속성은 $select를 사용하여 반환됩니다. 속성을 지정하지 않으면 오류가 반환됩니다.
결과 필터링
$filter 시스템 쿼리 옵션을 사용하여 행이 반환될 기준을 설정합니다.
표준 필터 연산자
웹 API는 다음 표에 나열된 표준 OData 필터 연산자를 지원합니다.
| Operator | 설명 | 예제 |
|---|---|---|
| 비교 연산자 | ||
| eq | 같음 | $filter=revenue eq 100000 |
| ne | 같지 않음 | $filter=revenue ne 100000 |
| gt | 보다 큼 | $filter=revenue gt 100000 |
| ge | 보다 크거나 같음 | $filter=revenue ge 100000 |
| lt | 보다 작음 | $filter=revenue lt 100000 |
| le | 보다 작거나 같음 | $filter=revenue le 100000 |
| 논리 연산자 | ||
| and | 논리적 및 | $filter=revenue lt 100000 and revenue gt 2000 |
| or | 논리적 또는 | $filter=contains(name,'(sample)') or contains(name,'test') |
| not | 논리적 부정 | $filter=not contains(name,'sample') |
| 그룹화 연산자 | ||
| ( ) | 우선 순위 그룹화 | (contains(name,'sample') or contains(name,'test')) and revenue gt 5000 |
표준 쿼리 함수
웹 API는 다음과 같은 표준 OData 문자열 쿼리 함수를 지원합니다.
| 함수 | 예제 |
|---|---|
| contains | $filter=contains(name,'(sample)') |
| endswith | $filter=endswith(name,'Inc.') |
| startswith | $filter=startswith(name,'a') |
Dataverse 쿼리 함수
웹 API는 Dataverse 쿼리 기능을 지원하여 결과를 필터링합니다. 자세한 내용은 웹 API 쿼리 함수 참조를 참조하세요.
순서 결과
$orderby 시스템 쿼리 옵션을 사용하여 항목이 반환되는 순서를 지정합니다. asc 또는 desc 접미사를 사용하여 각각 오름차순과 내림차순을 지정합니다. 접미사가 적용되지 않은 경우 기본값은 오름차순입니다. 다음 예에서는 수익 오름차순 및 이름 내림차순으로 정렬된 계정의 이름 및 수익 속성을 검색하는 방법을 보여줍니다.
| Method | URI |
|---|---|
| 가져오기 |
[Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000
예제: https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000 |
결과 집계 및 그룹화
$apply를 사용하여 다음 예와 같이 데이터를 동적으로 집계하고 그룹화할 수 있습니다.
| 시나리오 | 예제 |
|---|---|
| 쿼리의 고유 상태 목록 | accounts?$apply=groupby((statuscode)) |
| 예상 값을 집계한 합계입니다. | opportunities?$apply=aggregate(estimatedvalue with sum as total) |
| 예상 가치 및 상태에 따른 평균 거래 규모 | opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue) |
| 상태에 따른 추정 가치의 합계 | opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total)) |
| 계정 이름별 총 기회 수익 | opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total)) |
| 'WA' 계정의 기본 연락처 이름 | accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname)) |
| 마지막으로 레코드를 만든 날짜와 시간 | accounts?$apply=aggregate(createdon with max as lastCreate) |
| 처음으로 레코드를 만든 날짜와 시간 | accounts?$apply=aggregate(createdon with min as firstCreate) |
행 수 검색
$count 시스템 쿼리 옵션을 참 값과 함께 사용하여 최대 5,000개의 필터 기준과 일치하는 엔터티 수를 포함합니다.
| Method | URI |
|---|---|
| 가져오기 |
[Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true
예제: https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true |
샘플 응답
{
"@odata.count": 10,
"value": [
{
"@odata.etag": "W/\"1066412\"",
"name": "Fourth Coffee (sample)",
"accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
},
{
"@odata.etag": "W/\"1066413\"",
"name": "Litware, Inc. (sample)",
"accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
},
{
"@odata.etag": "W/\"1066414\"",
"name": "Adventure Works (sample)",
"accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}
]
}
개수를 제외한 데이터를 반환하지 않으려면 컬렉션에 $count를 적용하여 값만 가져올 수 있습니다.
| Method | URI |
|---|---|
| 가져오기 |
[Portal URI/_api/accounts/$count
예제: https://contoso.powerappsportals.com/_api/accounts/$count |
샘플 응답
3
열 비교
다음 예에서는 웹 API를 사용하여 열을 비교하는 방법을 보여줍니다.
| Method | URI |
|---|---|
| GET |
[Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname
예제: https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname |
쿼리로 관련 테이블 레코드 검색
탐색 속성에서 $expand 시스템 쿼리 옵션을 사용하여 관련 엔터티에서 반환되는 데이터를 제어합니다.
관련 탐색 속성 조회
$expand 쿼리 옵션을 사용할 때 조회 속성으로 Microsoft.Dynamics.CRM.associatednavigationproperty을 사용해야 합니다.
특성의 Microsoft.Dynamics.CRM.associatednavigationproperty를 결정하려면 _name_value 명명 규칙을 사용하여 열에 대해 다음 http GET 요청을 수행할 수 있습니다.
다음 예제에서는 요청 _primarycontactid_value의 이름 형식을 지정함으로써 열 이름 primarycontactid을 지정하여 거래처 테이블의 기본 연락처 열에 연결된 탐색 속성을 결정할 수 있습니다.
| Method | URI |
|---|---|
| GET |
[Portal URI]/_api/accounts?$select=_primarycontactid_value
예제 https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value |
샘플 응답
{
"value": [
{
"@odata.etag": "W/\"2465216\"",
"_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Yvonne McKay (sample)",
"_primarycontactid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "primarycontactid",
"_primarycontactid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "contact",
"_primarycontactid_value": "417319b5-cd18-ed11-b83c-000d3af4d812",
"accountid": "2d7319b5-cd18-ed11-b83c-000d3af4d812"
}
]
}
응답에서 연결된 탐색 속성이 primarycontactid임을 알 수 있습니다. 연결된 탐색 속성은 테이블이 생성된 방식에 따라 조회 열의 논리적 이름 또는 스키마 이름일 수 있습니다.
자세한 내용은 조회 속성에 대한 데이터 검색을 참조하십시오.
단일 값 탐색 속성을 확장하여 관련 테이블 레코드 검색
다음 예는 모든 계정 레코드에 대한 연락처를 검색하는 방법을 보여줍니다. 관련 연락처 기록에 대해서는 연락처 및 이름만 검색합니다.
| Method | URI |
|---|---|
| GET |
[Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)
예제: https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname) |
샘플 응답
{
"value": [
{
"@odata.etag": "W/\"1066412\"",
"name": "Fourth Coffee (sample)",
"accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607",
"primarycontactid": {
"contactid": "e6e11ba8-92f6-eb11-94ef-000d3a5aa607",
"fullname": "Yvonne McKay (sample)"
}
},
{
"@odata.etag": "W/\"1066413\"",
"name": "Litware, Inc. (sample)",
"accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607",
"primarycontactid": {
"contactid": "e8e11ba8-92f6-eb11-94ef-000d3a5aa607",
"fullname": "Susanna Stubberod (sample)"
}
}
]
}
컬렉션 값 탐색 속성을 확장하여 관련 테이블 검색
컬렉션 반환 탐색 매개 변수를 확장하여 엔터티 집합에 대한 관련 테이블을 검색하는 경우 데이터가 있으면 한 수준의 깊이만 반환됩니다. 그렇지 않으면 컬렉션은 빈 배열을 반환합니다.
| Method | URI |
|---|---|
| 가져오기 |
[Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)
예제: https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart) |
단일 값과 컬렉션 값 탐색 속성을 확장하여 관련 테이블 검색
다음 예제에서는 단일 및 컬렉션 반환 탐색 속성을 모두 사용하여 엔터티 집합에 대한 관련 엔터티를 확장하는 방법을 보여 줍니다. 코드 구문에서 테이블 관계 이름을 지정해야 합니다.
| Method | URI |
|---|---|
| 가져오기 |
[Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)
예제: https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart) |
다음 단계
포털은 웹 API를 사용하여 작업을 쓰고 업데이트하고 삭제합니다