다음을 통해 공유

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

  • 아티클

참고

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

포털에서 사용 가능한 웹 API 작업을 사용할 수 있습니다. 웹 API 작업은 HTTP 요청 및 응답으로 구성됩니다. 이 문서에서는 HTTP 요청에서 사용할 수 있는 샘플 읽기 작업, 메서드, URI 및 샘플 JSON을 제공합니다.

전제 조건

  • 포털 버전은 9.4.1.x 이상이어야 합니다.

  • 웹 API 작업을 위한 테이블 및 필드를 활성화합니다. 추가 정보: 웹 API에 대한 사이트 설정

  • 포털 웹 API는 테이블 레코드에 액세스하고 연결된 웹 역할을 통해 사용자에게 부여된 테이블 권한을 따릅니다. 올바른 테이블 권한을 구성했는지 확인하세요. 추가 정보: 웹 역할 만들기

참고

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

레코드 쿼리

다음 예에서는 계정 레코드를 쿼리합니다.

작업 Method URI
테이블 레코드 검색 GET [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개의 엔터티 레코드 검색 GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

예제:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

계정 ID를 사용하여 계정 검색:

작업 Method URI
레코드의 특정 속성 검색 GET [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
GET [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
GET [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
GET [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
GET [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
GET [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
GET [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
GET [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를 사용하여 작업을 쓰고 업데이트하고 삭제합니다

참고 항목:

포털 웹 API 개요
자습서: 포털 웹 API 사용
열 권한 구성

참고

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

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