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

아티클
12/31/2024

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)`

FetchXml을 사용하여 레코드 쿼리

FetchXml 쿼리 매개 변수를 사용하여 FetchXml 쿼리를 URL로 인코딩된 문자열 값으로 엔터티 집합 컬렉션에 전달해야 합니다.

예를 들어, 거래처 엔터티 집합에서 데이터를 검색하려면 엔터티 요소 이름 매개 변수를 거래처로 설정하는 FetchXml 쿼리를 작성합니다.

<fetch top='2'>
  <entity name='account'>
      <attribute name='name' />
  </entity>
</fetch>

이전 쿼리에 대한 URL 인코딩 문자열은 다음과 같습니다.

%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E

Method	URI
GET	`[Portal URI]/_api/accounts?fetchxml` 예: `https://contoso.powerappsportals.com/_api/accounts?fetchXml=%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E`

샘플 응답

{
  "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)"
      }
    }
  ]
}

다음 단계

포털은 웹 API를 사용하여 작업을 쓰고 업데이트하고 삭제합니다

다음을 통해 공유

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

전제 조건

레코드 쿼리

시스템 쿼리 옵션 적용

요청별 속성

결과 필터링

표준 필터 연산자

표준 쿼리 함수

Dataverse 쿼리 함수

순서 결과

결과 집계 및 그룹화

행 수 검색

열 비교

관련 탐색 속성 조회

FetchXml을 사용하여 레코드 쿼리

다음 단계

참조 항목

피드백

추가 리소스

다음을 통해 공유

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

전제 조건

레코드 쿼리

시스템 쿼리 옵션 적용

요청별 속성

결과 필터링

표준 필터 연산자

표준 쿼리 함수

Dataverse 쿼리 함수

순서 결과

결과 집계 및 그룹화

행 수 검색

열 비교

쿼리로 관련 테이블 레코드 검색

관련 탐색 속성 조회

단일 값 탐색 속성을 확장하여 관련 테이블 레코드 검색

컬렉션 값 탐색 속성을 확장하여 관련 테이블 검색

단일 값과 컬렉션 값 탐색 속성을 확장하여 관련 테이블 검색

FetchXml을 사용하여 레코드 쿼리

다음 단계

참조 항목

피드백

추가 리소스