클라이언트 API Dataverse 레코드, 파일 및 이미지

$pages.webAPI 개체

Power Pages Client API $pages.webAPI 개체를 사용하여 Dataverse 레코드를 만들고, 검색하고, 업데이트하고, 삭제하고, 파일 및 이미지 열에 저장된 콘텐츠를 사용할 수 있습니다.

메서드	Description
`createRecord`	지정된 테이블에 새 레코드를 만듭니다.
`retrieveRecord`	고유 식별자를 사용하여 레코드를 검색합니다.
`retrieveMultipleRecords`	제공된 쿼리 옵션에 따라 여러 레코드를 검색합니다.
`updateRecord`	지정된 테이블의 기존 레코드를 업데이트합니다.
`deleteRecord`	지정된 테이블에서 레코드를 삭제합니다.
`updateSingleProperty`	기존 레코드의 단일 열 값을 업데이트합니다.
`deleteSingleProperty`	Null로 설정하여 기존 레코드의 단일 열 값을 지웁니다.
`associateRecord`	컬렉션 반환 탐색 속성을 사용하여 두 레코드 간의 연결을 만듭니다.
`disassociateRecord`	두 레코드 간의 연결을 제거합니다.
`getRecordCount`	지정된 테이블의 총 레코드 수를 반환합니다.
`uploadFileToColumn`	파일 또는 이미지를 기존 레코드의 파일 열 또는 이미지 열에 업로드합니다.
`downloadFileFromColumn`	파일 열의 이진 콘텐츠 또는 기존 레코드의 이미지 열을 다운로드합니다.

createRecord 메서드

지정된 테이블에 새 레코드를 만듭니다.

구문: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<string>
반환: 만든 레코드의 ID로 확인되는 Promise 입니다.

createRecord 메서드 매개 변수

만들 레코드를 나타내는 대상 테이블과 데이터 개체를 제공합니다.

매개 변수	Type	Description
`entitySetName`	string	엔터티 집합의 이름입니다. Dataverse Web API의 엔터티 집합 이름에 대해 알아보기
`data`	object	만들 레코드 데이터입니다.

createRecord 메서드 예제

이 예제에서는 엔터티 집합 이름과 최소 데이터 개체를 사용하여 호출 createRecord 하는 방법을 보여 줍니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    $pages.webAPI.createRecord('contacts', {
        firstName: 'User',
        lastName: 'Test'
    });
});

retrieveRecord 메서드

고유 식별자를 사용하여 레코드를 검색합니다.

구문: $pages.webAPI.retrieveRecord(entitySetName: string, id: string, options?: string): Promise<object>
반환: 레코드 개체로 확인되는 Promise 입니다.

retrieveRecord 메서드 매개 변수

테이블, 레코드 ID 및 선택적 OData $select 쿼리 옵션을 지정하여 응답을 셰이프합니다.

매개 변수	Type	Description
`entitySetName`	string	엔터티 집합의 이름입니다. Dataverse Web API의 엔터티 집합 이름에 대해 알아봅니다.
`id`	string	레코드의 고유 식별자입니다.
`options`	문자열(선택 사항)	반환되는 데이터를 제한하는 선택적 OData `$select` 쿼리 문자열입니다.

메모

options 매개 변수는 선택 사항이지만 최상의 성능을 위해 항상 옵션을 사용하여 $select반환되는 열 값의 수를 제한합니다.

retrieveRecord 메서드 예제

이 예제에서는 ID별로 단일 레코드를 검색하고 OData $select 쿼리 옵션을 사용하여 반환된 열을 제한합니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let record = await $pages.webAPI.retrieveRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',  '$select=name');
});

retrieveMultipleRecords 메서드

제공된 쿼리 옵션에 따라 여러 레코드를 검색합니다.

구문: $pages.webAPI.retrieveMultipleRecords(entitySetName: string, options?: string): Promise<object>
반환: OData 응답 개체로 확인되는 Promise 입니다. 응답의 속성에는 value 레코드 배열이 포함됩니다.

retrieveMultipleRecords 메서드 매개 변수

결과를 필터링하고 반환된 열을 제한하려면 테이블 및 선택적 OData 쿼리를 지정합니다.

매개 변수	Type	Description
`entitySetName`	string	엔터티 집합의 이름입니다.
`options`	문자열(선택 사항)	반환된 데이터를 제어하는 OData 쿼리 옵션 문자열입니다. Dataverse Web API에서 지원하는 OData 쿼리 옵션에 대해 자세히 알아보기

메모

options 매개 변수는 선택 사항이지만 최상의 성능을 위해 항상 옵션을 사용하여 $select반환되는 열 값의 수를 제한합니다.

retrieveMultipleRecords 메서드 예제

이 예제에서는 여러 레코드를 검색하고 OData $select$top 를 사용하여 반환된 열과 행 수를 제한합니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let response = await $pages.webAPI.retrieveMultipleRecords('accounts', '$select=name&$top=3');
    let records = response.value;
    console.log(`Retrieved ${records.length} records.`);
});

updateRecord 메서드

지정된 테이블의 기존 레코드를 업데이트합니다.

구문: $pages.webAPI.updateRecord(entitySetName: string, id: string, data: object): Promise<void>
반환: 레코드가 업데이트될 때 확인되는 Promise 입니다.

updateRecord 메서드 매개 변수

테이블, 업데이트할 레코드 및 설정할 열 값을 지정합니다.

매개 변수	Type	Description
`entitySetName`	string	엔터티 집합의 이름입니다.
`id`	string	업데이트할 레코드의 고유 식별자입니다.
`data`	object	업데이트할 열 및 값입니다.

updateRecord 메서드 예제

다음은 계정 레코드의 이름을 업데이트하는 예제입니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.updateRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', { name: 'Updated Name' });
});

deleteRecord 메서드

지정된 테이블에서 레코드를 삭제합니다.

구문: $pages.webAPI.deleteRecord(entitySetName: string, id: string): Promise<void>
반환: 레코드가 삭제될 때 확인되는 Promise 입니다.

deleteRecord 메서드 매개 변수

삭제할 테이블과 레코드를 지정합니다.

매개 변수	Type	Description
`entitySetName`	string	엔터티 집합의 이름입니다.
`id`	string	삭제할 레코드의 고유 식별자입니다.

deleteRecord 메서드 예제

다음은 계정 레코드를 삭제하는 예제입니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.deleteRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb');
});

updateSingleProperty 메서드

기존 레코드의 단일 열 값을 업데이트합니다.

구문: $pages.webAPI.updateSingleProperty(entitySetName: string, id: string, property: string, value: unknown): Promise<void>
반환: 열이 업데이트될 때 확인되는 Promise 입니다.

updateSingleProperty 메서드 매개 변수

테이블, 레코드, 업데이트할 열 및 새 값을 지정합니다.

매개 변수	Type	Description
`entitySetName`	string	엔터티 집합의 이름입니다.
`id`	string	레코드의 고유 식별자.
`property`	string	업데이트할 열의 이름입니다.
`value`	unknown	열의 새 값입니다.

updateSingleProperty 메서드 예제

다음은 계정 레코드의 이름 열을 업데이트하는 예제입니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.updateSingleProperty('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'name', 'New Name');
});

deleteSingleProperty 메서드

Null로 설정하여 기존 레코드의 단일 열 값을 지웁니다.

구문: $pages.webAPI.deleteSingleProperty(entitySetName: string, id: string, property: string): Promise<void>
반환: 열 값이 지워지면 확인되는 Promise 입니다.

deleteSingleProperty 메서드 매개 변수

지울 테이블, 레코드 및 열을 지정합니다.

매개 변수	Type	Description
`entitySetName`	string	엔터티 집합의 이름입니다.
`id`	string	레코드의 고유 식별자.
`property`	string	지울 열의 이름입니다.

deleteSingleProperty 메서드 예제

다음은 계정 레코드의 설명 열을 지우는 예제입니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.deleteSingleProperty('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'description');
});

associateRecord 메서드

컬렉션 반환 탐색 속성을 사용하여 두 레코드 간의 연결을 만듭니다. 이 메서드는 OData $ref 작업을 사용하여 링크를 만듭니다.

구문: $pages.webAPI.associateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
반환: 레코드가 연결된 시기를 확인하는 Promise 입니다.

associateRecord 메서드 매개 변수

먼저 부모 레코드를 지정한 다음 탐색 속성 및 관련 레코드를 지정합니다.

매개 변수	Type	Description
`entitySetName`	string	관계의 한쪽에 있는 부모 레코드의 엔터티 집합 이름입니다.
`id`	string	부모 레코드의 고유 식별자입니다.
`navigationProperty`	string	관계를 정의하는 컬렉션 반환 탐색 속성의 이름입니다.
`relatedEntitySetName`	string	관계의 여러 쪽에 있는 관련 레코드의 엔터티 집합 이름입니다.
`relatedId`	string	연결할 관련 레코드의 고유 식별자입니다.

Important

항상 관계와 매개 변수를 사용하여 먼저 관계의 한쪽에 부모 레코드를 entitySetNameid 지정합니다.

associateRecord 메서드 예제

다음은 탐색 속성을 사용하여 contact_association 연락처 레코드를 계정 레코드와 연결하는 예제입니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.associateRecord(
        'accounts',
        'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        'contact_association',
        'contacts',
        'cccccccc-0000-1111-2222-dddddddddddd'
    );
});

disassociateRecord 메서드

두 레코드 간의 연결을 제거합니다.

구문: $pages.webAPI.disassociateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
반환: 연결이 제거될 때 확인되는 Promise 입니다.

disassociateRecord 메서드 매개 변수

먼저 부모 레코드를 지정한 다음 탐색 속성 및 관련 레코드를 지정합니다.

매개 변수	Type	Description
`entitySetName`	string	관계의 한쪽에 있는 부모 레코드의 엔터티 집합 이름입니다.
`id`	string	부모 레코드의 고유 식별자입니다.
`navigationProperty`	string	관계를 정의하는 컬렉션 반환 탐색 속성의 이름입니다.
`relatedEntitySetName`	string	관련 레코드의 엔터티 집합 이름입니다.
`relatedId`	string	연결 해제할 관련 레코드의 고유 식별자입니다.

Important

항상 관계와 매개 변수를 사용하여 먼저 관계의 한쪽에 부모 레코드를 entitySetNameid 지정합니다.

disassociateRecord 메서드 예제

다음은 계정 레코드와 연락처 레코드 간의 연결을 제거하는 예제입니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.disassociateRecord(
        'accounts',
        'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        'contact_association',
        'contacts',
        'cccccccc-0000-1111-2222-dddddddddddd'
    );
});

getRecordCount 메서드

지정된 테이블의 총 레코드 수를 반환합니다. 이 메서드는 레코드 컬렉션 대신 정수 값을 반환하는 OData /$count 엔드포인트를 호출합니다.

구문: $pages.webAPI.getRecordCount(entitySetName: string): Promise<number>
반환: 레코드 수로 확인되는 Promise 입니다.

getRecordCount 메서드 매개 변수

레코드 수를 계산할 테이블을 지정합니다.

매개 변수	Type	Description
`entitySetName`	string	엔터티 집합의 이름입니다.

메모

서버는 최대 5,000개의 수를 반환합니다. 테이블에 5,000개 이상의 레코드가 포함된 경우 결과는 5,000개입니다. 레코드를 총 개수와 함께 검색하려면 쿼리 옵션과 함께 retrieveMultipleRecords 메서드를 $count=true 대신 사용합니다. 이 메서드는 응답 속성의 value 컬렉션과 속성의 총 개수를 @odata.count 반환합니다.

getRecordCount 메서드 예제

이 예제에서는 총 계정 레코드 수를 반환합니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const total = await $pages.webAPI.getRecordCount('accounts');
    console.log(`Total accounts: ${total}`);
});

uploadFileToColumn 메서드

파일 또는 이미지를 기존 레코드의 파일 열 또는 이미지 열에 업로드합니다. Dataverse는 이진 콘텐츠를 저장하고 파일 이름으로 열을 자동으로 업데이트합니다 {columnName}_Name .

구문: $pages.webAPI.uploadFileToColumn(entitySetName: string, id: string, columnName: string, file: File): Promise<void>
반환: 파일이 업로드될 때 확인되는 Promise 입니다.

uploadFileToColumn 메서드 매개 변수

업로드할 테이블, 레코드, 열 및 파일을 지정합니다.

매개 변수	Type	Description
`entitySetName`	string	엔터티 집합의 이름입니다.
`id`	string	레코드의 고유 식별자.
`columnName`	string	파일 또는 이미지 열의 논리적 이름입니다.
`file`	파일	업로드할 파일입니다.

메모

이미지 열에 이 메서드를 사용할 수 있습니다. Dataverse는 서버에서 EXIF 메타데이터를 제거하고 썸네일을 자동으로 생성합니다. downloadFileFromColumn 메서드를 사용하여 전체 이미지 또는 썸네일을 다운로드합니다.

uploadFileToColumn 메서드 예제

다음은 파일 입력 요소를 사용하여 선택한 파일을 업로드하는 예제입니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const fileInput = document.querySelector('input[type="file"]');

    if (!fileInput || fileInput.files.length === 0) {
        return;
    }

    const file = fileInput.files[0];
    await $pages.webAPI.uploadFileToColumn('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'new_attachment', file);
});

downloadFileFromColumn 메서드

파일 열의 이진 콘텐츠 또는 기존 레코드의 이미지 열을 다운로드합니다. 큰 파일은 4MB 청크로 다운로드되고 단일 Blob으로 자동으로 결합됩니다.

구문: $pages.webAPI.downloadFileFromColumn(entitySetName: string, id: string, columnName: string, options?: object): Promise<Blob>
반환: 이진 데이터가 포함된 Blob으로 확인되는 Promise입니다. Blob의 속성에는 type 서버에서 반환하는 MIME 형식이 포함됩니다.

downloadFileFromColumn 메서드 매개 변수

다운로드할 테이블, 레코드 및 열을 지정합니다.

매개 변수	Type	Description
`entitySetName`	string	엔터티 집합의 이름입니다.
`id`	string	레코드의 고유 식별자.
`columnName`	string	파일 또는 이미지 열의 논리적 이름입니다.
`options`	object(선택 사항)	다운로드 옵션입니다. 이 속성은 `size` 이미지 열에 적용되며 `full` 원래 이미지를 다운로드하거나 `thumbnail` Dataverse에서 생성하는 썸네일을 다운로드할 수 있습니다. 기본값은 `full`입니다.

메모

응답에는 파일 이름이 포함되지 않습니다. 파일 이름을 얻으려면 retrieveRecord 메서드 를 사용하여 레코드의 열을 쿼리 {columnName}_Name 합니다.

downloadFileFromColumn 메서드 예제

다음은 파일 열에서 파일을 다운로드하고 브라우저에 파일을 저장하라는 메시지를 표시하는 예제입니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const blob = await $pages.webAPI.downloadFileFromColumn('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'new_attachment');

    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'downloaded_file';
    a.click();
    URL.revokeObjectURL(url);
});

다음은 이미지 열에서 전체 이미지와 썸네일을 다운로드하는 예제입니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    // Full-resolution image, which is the default.
    const fullBlob = await $pages.webAPI.downloadFileFromColumn('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'entityimage');

    // Thumbnail that Dataverse generates.
    const thumbnailBlob = await $pages.webAPI.downloadFileFromColumn(
        'accounts',
        'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        'entityimage',
        { size: 'thumbnail' }
    );
});

피드백

이 페이지가 도움이 되었나요?

2026-09-21 에 마지막으로 업데이트됨