Dataverse-Datensätze, Dateien und Bilder der Client-API

$pages.webAPI-Objekt

Verwenden Sie das Power Pages Client-API-Objekt $pages.webAPI zum Erstellen, Abrufen, Aktualisieren und Löschen von Dataverse-Datensätzen und zum Arbeiten mit Inhalten, die in Datei- und Bildspalten gespeichert sind.

Methode Description
createRecord Erstellt einen neuen Datensatz in der angegebenen Tabelle.
retrieveRecord Ruft einen Datensatz anhand seines eindeutigen Bezeichners ab.
retrieveMultipleRecords Ruft mehrere Datensätze basierend auf den bereitgestellten Abfrageoptionen ab.
updateRecord Aktualisiert einen vorhandenen Datensatz in der angegebenen Tabelle.
deleteRecord Löscht einen Datensatz aus der angegebenen Tabelle.
updateSingleProperty Aktualisiert einen einzelnen Spaltenwert eines vorhandenen Datensatzes.
deleteSingleProperty Löscht den Wert einer einzelnen Spalte in einem vorhandenen Datensatz, indem er auf NULL festgelegt wird.
associateRecord Erstellt eine Zuordnung zwischen zwei Datensätzen mithilfe einer Sammlungswert-Navigationseigenschaft.
disassociateRecord Entfernt eine Zuordnung zwischen zwei Datensätzen.
getRecordCount Gibt die Gesamtzahl der Datensätze in der angegebenen Tabelle zurück.
uploadFileToColumn Lädt eine Datei oder ein Bild in eine Dateispalte oder eine Bildspalte eines vorhandenen Datensatzes hoch.
downloadFileFromColumn Lädt den binären Inhalt einer Dateispalte oder einer Bildspalte eines vorhandenen Datensatzes herunter.

createRecord-Methode

Erstellt einen neuen Datensatz in der angegebenen Tabelle.

Syntax: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<string>
Gibt zurück: Eine Zusage , die in die ID des erstellten Datensatzes aufgelöst wird.

parameter der createRecord-Methode

Geben Sie die Zieltabelle und das Datenobjekt an, das den zu erstellenden Datensatz darstellt.

Parameter Type Description
entitySetName string Der Name des Entitätssatzes. Informationen zum Entitätssatznamen in der Dataverse-Web-API
data Objekt Die zu erstellenden Datensatzdaten.

createRecord-Methode (Beispiel)

In diesem Beispiel wird das Aufrufen createRecord mit einem Entitätssatznamen und einem minimalen Datenobjekt veranschaulicht.

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

retrieveRecord-Methode

Ruft einen Datensatz anhand seines eindeutigen Bezeichners ab.

Syntax: $pages.webAPI.retrieveRecord(entitySetName: string, id: string, options?: string): Promise<object>
Gibt zurück: Eine Zusage , die in das Datensatzobjekt aufgelöst wird.

parameter der retrieveRecord-Methode

Geben Sie die Tabellen-, Datensatz-ID- und optionalen OData-Abfrageoptionen $select an, um die Antwort zu gestalten.

Parameter Type Description
entitySetName string Der Name des Entitätssatzes. Erfahren Sie mehr über den Entitätssatznamen in der Dataverse-Web-API.
id string Der eindeutige Bezeichner des Datensatzes.
options String (optional) Eine optionale OData-Abfragezeichenfolge $select , um die zurückgegebenen Daten einzuschränken.

Note

Während der options Parameter optional ist, beschränken Sie für optimale Leistung immer die Anzahl der spaltenwerte, die mithilfe der $select Option zurückgegeben werden.

RetrieveRecord-Methode (Beispiel)

In diesem Beispiel wird ein einzelner Datensatz nach ID abgerufen und die zurückgegebenen Spalten mithilfe einer OData-Abfrageoption $select beschränkt.

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

retrieveMultipleRecords-Methode

Ruft mehrere Datensätze basierend auf den bereitgestellten Abfrageoptionen ab.

Syntax: $pages.webAPI.retrieveMultipleRecords(entitySetName: string, options?: string): Promise<object>
Gibt zurück: Eine Zusage , die in das OData-Antwortobjekt aufgelöst wird. Die value Eigenschaft der Antwort enthält das Array von Datensätzen.

retrieveMultipleRecords-Methodenparameter

Geben Sie die Tabelle und optionale OData-Abfrage an, um Ergebnisse zu filtern und zurückgegebene Spalten einzuschränken.

Parameter Type Description
entitySetName string Der Name des Entitätssatzes.
options String (optional) Eine OData-Abfrageoptionenzeichenfolge zum Steuern der zurückgegebenen Daten. Weitere Informationen zu OData-Abfrageoptionen, die von der Dataverse-Web-API unterstützt werden

Note

Während der options Parameter optional ist, beschränken Sie für optimale Leistung immer die Anzahl der spaltenwerte, die mithilfe der $select Option zurückgegeben werden.

retrieveMultipleRecords-Methode (Beispiel)

In diesem Beispiel werden mehrere Datensätze abgerufen und OData $select verwendet, um $top zurückgegebene Spalten und Zeilenanzahl einzuschränken.

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-Methode

Aktualisiert einen vorhandenen Datensatz in der angegebenen Tabelle.

Syntax: $pages.webAPI.updateRecord(entitySetName: string, id: string, data: object): Promise<void>
Gibt zurück: Eine Zusage , die beim Aktualisieren des Datensatzes aufgelöst wird.

parameter der updateRecord-Methode

Geben Sie die Tabelle, den zu aktualisierenden Datensatz und die festzulegenden Spaltenwerte an.

Parameter Type Description
entitySetName string Der Name des Entitätssatzes.
id string Der eindeutige Bezeichner des zu aktualisierenden Datensatzes.
data Objekt Die zu aktualisierenden Spalten und Werte.

UpdateRecord-Methode (Beispiel)

In diesem Beispiel wird der Name eines Kontodatensatzes aktualisiert.

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

deleteRecord-Methode

Löscht einen Datensatz aus der angegebenen Tabelle.

Syntax: $pages.webAPI.deleteRecord(entitySetName: string, id: string): Promise<void>
Gibt zurück: Eine Zusage , die beim Löschen des Datensatzes aufgelöst wird.

deleteRecord-Methodenparameter

Geben Sie die Zu löschende Tabelle und den zu löschenden Datensatz an.

Parameter Type Description
entitySetName string Der Name des Entitätssatzes.
id string Der eindeutige Bezeichner des zu löschenden Datensatzes.

DeleteRecord-Methode (Beispiel)

In diesem Beispiel wird ein Kontodatensatz gelöscht.

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

updateSingleProperty-Methode

Aktualisiert einen einzelnen Spaltenwert eines vorhandenen Datensatzes.

Syntax: $pages.webAPI.updateSingleProperty(entitySetName: string, id: string, property: string, value: unknown): Promise<void>
Gibt zurück: Eine Zusage , die beim Aktualisieren der Spalte aufgelöst wird.

parameter der updateSingleProperty-Methode

Geben Sie die Tabelle, den Datensatz, die zu aktualisierende Spalte und den neuen Wert an.

Parameter Type Description
entitySetName string Der Name des Entitätssatzes.
id string Der eindeutige Bezeichner des Quelldatensatzes.
property string Der Name der zu aktualisierenden Spalte.
value Unbekannt Der neue Wert für die Spalte.

updateSingleProperty-Methode (Beispiel)

In diesem Beispiel wird die Namensspalte eines Kontodatensatzes aktualisiert.

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

deleteSingleProperty-Methode

Löscht den Wert einer einzelnen Spalte in einem vorhandenen Datensatz, indem er auf NULL festgelegt wird.

Syntax: $pages.webAPI.deleteSingleProperty(entitySetName: string, id: string, property: string): Promise<void>
Gibt zurück: Eine Zusage , die aufgelöst wird, wenn der Spaltenwert gelöscht wird.

deleteSingleProperty-Methodenparameter

Geben Sie die Tabelle, den Datensatz und die zu löschende Spalte an.

Parameter Type Description
entitySetName string Der Name des Entitätssatzes.
id string Der eindeutige Bezeichner des Quelldatensatzes.
property string Der Name der zu löschenden Spalte.

deleteSingleProperty-Methode (Beispiel)

In diesem Beispiel wird die Beschreibungsspalte eines Kontodatensatzes gelöscht.

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

associateRecord-Methode

Erstellt eine Zuordnung zwischen zwei Datensätzen mithilfe einer Sammlungswert-Navigationseigenschaft. Diese Methode verwendet den OData-Vorgang $ref , um den Link zu erstellen.

Syntax: $pages.webAPI.associateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
Gibt zurück: Eine Zusage , die aufgelöst wird, wenn die Datensätze zugeordnet sind.

associateRecord-Methodenparameter

Geben Sie zuerst den übergeordneten Datensatz und dann die Navigationseigenschaft und den zugehörigen Datensatz an.

Parameter Type Description
entitySetName string Der Entitätssatzname des übergeordneten Datensatzes auf der einen Seite der Beziehung.
id string Der eindeutige Bezeichner des übergeordneten Datensatzes.
navigationProperty string Der Name der Auflistungswert-Navigationseigenschaft, die die Beziehung definiert.
relatedEntitySetName string Der Entitätssatzname des verknüpften Datensatzes auf der n-Seite der Beziehung.
relatedId string Der eindeutige Bezeichner des zugeordneten Datensatzes.

Important

Geben Sie immer den übergeordneten Datensatz auf der 1-Seite der Beziehung zuerst mithilfe der entitySetName Parameter an id .

associateRecord-Methode (Beispiel)

In diesem Beispiel wird ein Kontaktdatensatz einem Kontodatensatz mithilfe der contact_association Navigationseigenschaft zugeordnet.

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-Methode

Entfernt eine Zuordnung zwischen zwei Datensätzen.

Syntax: $pages.webAPI.disassociateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
Gibt zurück: Eine Zusage , die aufgelöst wird, wenn die Zuordnung entfernt wird.

disassociateRecord-Methodenparameter

Geben Sie zuerst den übergeordneten Datensatz und dann die Navigationseigenschaft und den zugehörigen Datensatz an.

Parameter Type Description
entitySetName string Der Entitätssatzname des übergeordneten Datensatzes auf der einen Seite der Beziehung.
id string Der eindeutige Bezeichner des übergeordneten Datensatzes.
navigationProperty string Der Name der Auflistungswert-Navigationseigenschaft, die die Beziehung definiert.
relatedEntitySetName string Der Entitätssatzname des verknüpften Datensatzes.
relatedId string Der eindeutige Bezeichner des verknüpften Datensatzes, der die Zuordnung aufheben soll.

Important

Geben Sie immer den übergeordneten Datensatz auf der 1-Seite der Beziehung zuerst mithilfe der entitySetName Parameter an id .

disassociateRecord-Methode (Beispiel)

In diesem Beispiel wird die Zuordnung zwischen einem Kontodatensatz und einem Kontaktdatensatz entfernt.

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-Methode

Gibt die Gesamtzahl der Datensätze in der angegebenen Tabelle zurück. Diese Methode ruft den OData-Endpunkt /$count auf, der eine ganze Zahl anstelle einer Auflistung von Datensätzen zurückgibt.

Syntax: $pages.webAPI.getRecordCount(entitySetName: string): Promise<number>
Gibt zurück: Eine Zusage , die zur Anzahl der Datensätze aufgelöst wird.

parameter der getRecordCount-Methode

Geben Sie die Tabelle an, in der Datensätze gezählt werden sollen.

Parameter Type Description
entitySetName string Der Name des Entitätssatzes.

Note

Der Server gibt eine maximale Anzahl von 5.000 zurück. Wenn eine Tabelle mehr als 5.000 Datensätze enthält, beträgt das Ergebnis 5.000. Um Datensätze zusammen mit der Gesamtanzahl abzurufen, verwenden Sie stattdessen die RetrieveMultipleRecords-Methode mit der $count=true Abfrageoption . Diese Methode gibt die Auflistung in der value Eigenschaft der Antwort und die Gesamtanzahl in der @odata.count Eigenschaft zurück.

getRecordCount-Methode (Beispiel)

In diesem Beispiel wird die Gesamtzahl der Kontodatensätze zurückgegeben.

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

uploadFileToColumn-Methode

Lädt eine Datei oder ein Bild in eine Dateispalte oder eine Bildspalte eines vorhandenen Datensatzes hoch. Dataverse speichert den binären Inhalt und aktualisiert die {columnName}_Name Spalte automatisch mit dem Dateinamen.

Syntax: $pages.webAPI.uploadFileToColumn(entitySetName: string, id: string, columnName: string, file: File): Promise<void>
Gibt zurück: Eine Zusage , die beim Hochladen der Datei aufgelöst wird.

parameter der uploadFileToColumn-Methode

Geben Sie die Tabelle, den Datensatz, die Spalte und die hochzuladende Datei an.

Parameter Type Description
entitySetName string Der Name des Entitätssatzes.
id string Der eindeutige Bezeichner des Quelldatensatzes.
columnName string Der logische Name der Datei- oder Bildspalte.
file File Die hochzuladende Datei.

Note

Sie können diese Methode mit Bildspalten verwenden. Dataverse entfernt EXIF-Metadaten auf dem Server und generiert automatisch eine Miniaturansicht. Verwenden Sie die downloadFileFromColumn-Methode , um entweder das vollständige Bild oder die Miniaturansicht herunterzuladen.

uploadFileToColumn-Methode (Beispiel)

In diesem Beispiel wird eine Datei hochgeladen, die jemand mithilfe eines Dateieingabeelements auswählt.

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-Methode

Lädt den binären Inhalt einer Dateispalte oder einer Bildspalte eines vorhandenen Datensatzes herunter. Große Dateien werden in 4-MB-Blöcken heruntergeladen und automatisch in ein einzelnes Blob kombiniert.

Syntax: $pages.webAPI.downloadFileFromColumn(entitySetName: string, id: string, columnName: string, options?: object): Promise<Blob>
Gibt zurück: Eine Zusage , die in ein Blob aufgelöst wird, das die Binärdaten enthält. Die type Eigenschaft des Blobs enthält den MIME-Typ, den der Server zurückgibt.

parameter der downloadFileFromColumn-Methode

Geben Sie die Tabelle, den Datensatz und die Spalte an, aus der sie heruntergeladen werden sollen.

Parameter Type Description
entitySetName string Der Name des Entitätssatzes.
id string Der eindeutige Bezeichner des Quelldatensatzes.
columnName string Der logische Name der Datei- oder Bildspalte.
options -Objekt (optional) Optionen für den Download. Die size Eigenschaft gilt für Bildspalten und akzeptiert full das Herunterladen des Originalbilds oder thumbnail das Herunterladen der von Dataverse generierten Miniaturansicht. Der Standardwert ist full.

Note

Die Antwort enthält nicht den Dateinamen. Verwenden Sie zum Abrufen des Dateinamens die retrieveRecord-Methode , um die {columnName}_Name Spalte des Datensatzes abzufragen.

DownloadFileFromColumn-Methodenbeispiele

In diesem Beispiel wird eine Datei aus einer Dateispalte heruntergeladen und der Browser aufgefordert, sie zu speichern.

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);
});

In diesem Beispiel werden das vollständige Bild und die Miniaturansicht aus einer Bildspalte heruntergeladen.

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' }
    );
});