クライアント API Dataverse のレコード、ファイル、およびイメージ

$pages.webAPI オブジェクト

Power Pages Client API $pages.webAPI オブジェクトを使用して、Dataverse レコードの作成、取得、更新、削除を行い、ファイル列とイメージ列に格納されているコンテンツを操作します。

Method 説明
createRecord 指定したテーブルに新しいレコードを作成します。
retrieveRecord レコードを一意識別子で取得します。
retrieveMultipleRecords 指定されたクエリ オプションに基づいて複数のレコードを取得します。
updateRecord 指定したテーブル内の既存のレコードを更新します。
deleteRecord 指定したテーブルからレコードを削除します。
updateSingleProperty 既存のレコードの単一列の値を更新します。
deleteSingleProperty 既存のレコード内の 1 つの列の値を null に設定してクリアします。
associateRecord コレクション値ナビゲーション プロパティを使用して、2 つのレコード間の関連付けを作成します。
disassociateRecord 2 つのレコード間の関連付けを削除します。
getRecordCount 指定したテーブル内のレコードの合計数を返します。
uploadFileToColumn ファイルまたはイメージを既存のレコードのファイル列またはイメージ列にアップロードします。
downloadFileFromColumn ファイル列または既存のレコードの画像列のバイナリ コンテンツをダウンロードします。

createRecord メソッド

指定したテーブルに新しいレコードを作成します。

構文: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<string>
戻り値: 作成されたレコードの ID に解決される Promise 。

createRecord メソッドのパラメーター

作成するレコードを表すターゲット テーブルとデータ オブジェクトを指定します。

パラメーター タイプ 説明
entitySetName 文字列 エンティティセットの名前。 Dataverse Web API のエンティティ セット名について説明します
data オブジェクト 作成するレコード データ。

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 クエリ オプションを指定して、応答を整形します。

パラメーター タイプ 説明
entitySetName 文字列 エンティティセットの名前。 Dataverse Web API のエンティティ セット名について説明します。
id 文字列 レコードの一意識別子。
options string (省略可能) 省略可能な OData $select クエリ文字列。返されるデータを制限します。

Note

options パラメーターは省略可能ですが、パフォーマンスを最大限に高めるには、$select オプションを使用して返される列の値の数を常に制限します。

retrieveRecord メソッドの例

次の使用例は、1 つのレコードを 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 クエリを指定します。

パラメーター タイプ 説明
entitySetName 文字列 エンティティセットの名前。
options string (省略可能) 返されるデータを制御する OData クエリ オプション文字列。 Dataverse Web API でサポートされる OData クエリ オプションの詳細を確認する

Note

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 メソッドのパラメーター

テーブル、更新するレコード、および設定する列の値を指定します。

パラメーター タイプ 説明
entitySetName 文字列 エンティティセットの名前。
id 文字列 更新するレコードの一意識別子。
data オブジェクト 更新する列と値。

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 メソッドのパラメーター

削除するテーブルとレコードを指定します。

パラメーター タイプ 説明
entitySetName 文字列 エンティティセットの名前。
id 文字列 削除するレコードの一意識別子。

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 メソッドパラメーター

テーブル、レコード、更新する列、および新しい値を指定します。

パラメーター タイプ 説明
entitySetName 文字列 エンティティセットの名前。
id 文字列 レコードの一意識別子です。
property 文字列 更新する列の名前。
value 不明 列の新しい値。

updateSingleProperty メソッドの例

次の使用例は、取引先企業レコードの名前列を更新します。

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

deleteSingleProperty メソッド

既存のレコード内の 1 つの列の値を null に設定してクリアします。

構文: $pages.webAPI.deleteSingleProperty(entitySetName: string, id: string, property: string): Promise<void>
戻り値: 列の値がクリアされたときに解決される Promise 。

deleteSingleProperty メソッドパラメーター

クリアするテーブル、レコード、列を指定します。

パラメーター タイプ 説明
entitySetName 文字列 エンティティセットの名前。
id 文字列 レコードの一意識別子です。
property 文字列 クリアする列の名前。

deleteSingleProperty メソッドの例

次の使用例は、取引先企業レコードの説明列をクリアします。

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

associateRecord メソッド

コレクション値ナビゲーション プロパティを使用して、2 つのレコード間の関連付けを作成します。 このメソッドは、OData $ref 操作を使用してリンクを作成します。

構文: $pages.webAPI.associateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
戻り値: レコードが関連付けられているときに解決される Promise 。

associateRecord メソッドのパラメーター

最初に親レコードを指定し、次にナビゲーション プロパティと関連レコードを指定します。

パラメーター タイプ 説明
entitySetName 文字列 リレーションシップの一方の親レコードのエンティティ セット名。
id 文字列 親レコードの一意識別子。
navigationProperty 文字列 リレーションシップを定義するコレクション値ナビゲーション プロパティの名前。
relatedEntitySetName 文字列 リレーションシップの多くの側にある関連レコードのエンティティ セット名。
relatedId 文字列 関連付ける関連レコードの一意識別子。

Important

entitySetNameパラメーターとid パラメーターを使用して、リレーションシップの一方の側で常に親レコードを指定します。

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 メソッド

2 つのレコード間の関連付けを削除します。

構文: $pages.webAPI.disassociateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
戻り値: 関連付けが削除されたときに解決される Promise 。

disassociateRecord メソッドのパラメーター

最初に親レコードを指定し、次にナビゲーション プロパティと関連レコードを指定します。

パラメーター タイプ 説明
entitySetName 文字列 リレーションシップの一方の親レコードのエンティティ セット名。
id 文字列 親レコードの一意識別子。
navigationProperty 文字列 リレーションシップを定義するコレクション値ナビゲーション プロパティの名前。
relatedEntitySetName 文字列 関連レコードのエンティティ セット名。
relatedId 文字列 関連付けを解除する関連レコードの一意識別子。

Important

entitySetNameパラメーターとid パラメーターを使用して、リレーションシップの一方の側で常に親レコードを指定します。

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 メソッドのパラメーター

レコードをカウントするテーブルを指定します。

パラメーター タイプ 説明
entitySetName 文字列 エンティティセットの名前。

Note

サーバーは、最大カウント 5,000 を返します。 テーブルに 5,000 を超えるレコードが含まれている場合、結果は 5,000 になります。 レコードを合計カウントと共に取得するには、代わりに $count=true クエリ オプションを指定して retrieveMultipleRecords メソッドを使用します。 そのメソッドは、応答の 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 メソッドパラメーター

アップロードするテーブル、レコード、列、およびファイルを指定します。

パラメーター タイプ 説明
entitySetName 文字列 エンティティセットの名前。
id 文字列 レコードの一意識別子です。
columnName 文字列 ファイルまたはイメージ列の論理名。
file File アップロードするファイル。

Note

このメソッドは、イメージ列と共に使用できます。 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 メソッド

ファイル列または既存のレコードの画像列のバイナリ コンテンツをダウンロードします。 大きなファイルは 4 MB のチャンクでダウンロードされ、1 つの BLOB に自動的に結合されます。

構文: $pages.webAPI.downloadFileFromColumn(entitySetName: string, id: string, columnName: string, options?: object): Promise<Blob>
戻り値: バイナリ データを含む BLOB に解決される Promise。 BLOB の type プロパティには、サーバーが返す MIME の種類が含まれます。

downloadFileFromColumn メソッドパラメーター

ダウンロードするテーブル、レコード、および列を指定します。

パラメーター タイプ 説明
entitySetName 文字列 エンティティセットの名前。
id 文字列 レコードの一意識別子です。
columnName 文字列 ファイルまたはイメージ列の論理名。
options object (省略可能) ダウンロードのオプション。 size プロパティはイメージ列に適用され、元のイメージをダウンロードするfullを受け入れるか、Dataverse によって生成されるサムネイルをダウンロードするためのthumbnailを受け入れます。 既定値は full です。

Note

応答にはファイル名は含まれません。 ファイル名を取得するには、 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' }
    );
});
  • 最終更新: