Dataverse-Aktions- und Funktionsmethoden für generative Seiten

Verwenden Sie die Aktions- und Funktionsmethoden des dataApi Objekts, um benutzerdefinierte Dataverse-APIs aufzurufen, die an die Seite gebunden sind.

Hinweis

Aktions- und Funktionsmethoden sind im freigegebenen dataApi Vertrag optional. Einige Hosts implementieren sie nicht. Überprüfen Sie daher, ob eine Methode vorhanden ist, bevor Sie sie aufrufen. Eine vorhandene Methode bedeutet nicht, dass der Vorgang an die Seite gebunden ist, für die Laufzeit aktiviert oder für den aktuellen Benutzer zulässig ist. Im Gegensatz zu Verbindermethoden werden diese Methoden nie für erwartete Fehler ausgelöst. sie lösen stattdessen mit ok: false und einem Fehlercode. Behandeln Sie die Ergebnisse ok und error Eigenschaften explizit.

listBoundActions gibt die Aktionen und Funktionen zurück, die die aktuelle Laufzeitkonfiguration ermöglicht, wenn diese Ermittlung aktiviert ist; es ist keine Garantie dafür, dass der aktuelle Benutzer die Dataverse-Berechtigungen enthält, die zum Ausführen aller aufgelisteten Vorgänge erforderlich sind.

Methode	Description
executeAction	Ruft eine benutzerdefinierte Dataverse-API auf, die als Aktion an die Seite gebunden ist.
executeFunction	Ruft eine benutzerdefinierte Dataverse-API auf, die als Funktion an die Seite gebunden ist.
listBoundActions	Listet die an die Seite gebundenen benutzerdefinierten Dataverse-APIs (Aktionen und Funktionen) auf.

executeAction Methode

Ruft eine benutzerdefinierte Dataverse-API auf, die ein Hersteller als Aktion an die Seite gebunden hat (eine Meldung, die Daten ändern kann).

Parameters

Legen Sie einen Wert für diesen erforderlichen Parameter fest.

Name	Type	Description
request	DataverseActionRequest	Die Aktion, die aufgerufen werden soll, und deren Eingabeparameter.

DataverseActionRequest

Name	Type	Description
name	string	Der eindeutige Name der benutzerdefinierten API, dem Herausgeberpräfix, z new_ApproveExpenseReport. B. .
parameters	object	(Optional) Die Eingabeparameter, die für die Aktion erforderlich sind, schlüsselt nach eindeutigem Parameternamen.
boundTo	object	(Optional) Ein Verweis auf die Zielzeile (entityName und id) für entitätsgebundene Aktionen. Für globale (ungebundene) Aktionen auslassen.

Rücklieferungen

Eine Zusage , die ein DataverseActionResult enthält. Diese Methode löst niemals für erwartete Fehler (z. B. einen 403-Berechtigungsfehler, einen 400 ungültigen Parameter oder den Vorgang, der nicht gebunden oder aktiviert wird) aus. Überprüfen Sie stattdessen die ok Eigenschaft.

DataverseActionResult

Name	Type	Description
ok	boolean	Gibt an, ob die Aktion erfolgreich war.
status	number	Der von Dataverse zurückgegebene HTTP-Statuscode oder 0 wenn kein HTTP-Status verfügbar ist. Ein 0 Status kann bedeuten, dass die Laufzeit den Aufruf abgelehnt hat, not_enabledbevor er gesendet wird (z. B. , , not_bound, , not_permitted, wrong_operation_kind, oder invalid_parameterinvalid_bound_to), die Anforderung ohne HTTP-Antwort fehlgeschlagen ist oder das Ergebnis unbekannt ist (indeterminate ist true). Verwenden error.code Sie diese Fälle und indeterminate teilen Sie diese Fälle mit.
outputs	object	Die ausgabeparameter, die von der Aktion zurückgegeben werden, schlüsselt nach eindeutigem Namen. Leer für Aktionen ohne Ausgaben.
indeterminate	boolean	(Optional) true wenn ein Timeout oder ein anderer Ausfall nach der Versendung bedeutet, dass der Server die Aktion möglicherweise zugesichert hat; wiederholen Sie den Vorgang nicht automatisch.
error	object	(Optional) Fehlerdetails, wenn ok das ist false, einschließlich eines maschinenlesbaren code und einer sanitierten message. code ist einer von not_enabled, not_bound, not_permitted, wrong_operation_kind, invalid_parameter, invalid_bound_to, , , indeterminateoder , oder networkder HTTP-Statuscode der Aktion als Zeichenfolge (z. B "404". ), wenn Dataverse eine Fehlerantwort zurückgegeben hat oder "0" wenn kein HTTP-Status verfügbar war. not_permitted bedeutet, dass die Aktion oder Funktion nicht in der Zulassungsliste der Umgebung für generative Seiten enthalten ist – es gibt nicht an, ob der aktuelle Benutzer die Dataverse-Berechtigungen enthält, um sie auszuführen. Ein Berechtigungsfehler wird in der Regel wie status: 403 beim Fehlercode "403"angezeigt. Wenn der Host den HTTP-Status nicht ermitteln kann, wird er stattdessen zurückgegeben status: 0 .

executeAction-Beispiel

if (!dataApi.executeAction) {
  throw new Error("executeAction isn't available on this page.");
}

const result = await dataApi.executeAction({
  name: "new_ApproveExpenseReport",
  parameters: { comments: "Approved by manager" },
  boundTo: { entityName: "new_expensereport", id: "30dc51e9-947d-47d8-ad48-4fc48fba4a95" },
});

if (result.ok) {
  console.log(result.outputs);
}
else {
  console.log(result.error?.code);
}

executeFunction Methode

Ruft eine benutzerdefinierte Dataverse-API auf, die ein Hersteller als Funktion an die Seite gebunden hat (eine schreibgeschützte Nachricht mit GET-Semantik).

Parameters

Legen Sie einen Wert für diesen erforderlichen Parameter fest.

Name	Type	Description
request	DataverseFunctionRequest	Die Funktion, die aufgerufen werden soll, und deren Eingabeparameter.

DataverseFunctionRequest

Name	Type	Description
name	string	Der eindeutige Name der benutzerdefinierten API, dem Herausgeberpräfix, z new_GetExchangeRate. B. .
parameters	object	(Optional) Die eingabeparameter, die von der Funktion benötigt werden, mit Schlüsseln nach eindeutigem Parameternamen.
boundTo	object	(Optional) Ein Verweis auf die Zielzeile (entityName und id) für entitätsgebundene Funktionen. Weglassen für globale (ungebundene) Funktionen.

Rücklieferungen

Eine Zusage , die ein DataverseActionResult enthält. Wie bei executeActiondieser Methode wird niemals für erwartete Fehler ausgelöst – überprüfen Sie stattdessen die ok Eigenschaft.

executeFunction(Beispiel)

if (!dataApi.executeFunction) {
  throw new Error("executeFunction isn't available on this page.");
}

const result = await dataApi.executeFunction({
  name: "new_GetExchangeRate",
  parameters: { currencyCode: "EUR" },
});

if (result.ok) {
  console.log(result.outputs);
}

listBoundActions Methode

Listet die benutzerdefinierten Dataverse-APIs (Aktionen und Funktionen) auf, die ein Hersteller an die Seite gebunden hat.

Parameters

None.

Rücklieferungen

Eine Zusage , die ein Array von DataverseActionInfo-Einträgen enthält. Gibt ein leeres Array zurück, wenn die Ermittlung für die Laufzeit nicht aktiviert ist.

DataverseActionInfo

DataverseActionInfo gibt an, was der Hersteller der Seite für diese Aktion oder Funktion gebunden hat, nicht live Dataverse-Metadaten. Verwenden Sie sie nicht, um Eingabeformulare zu erstellen oder Ausgaben zu überprüfen – überprüfen Sie Parameteranforderungen und Ausgabe-Shapes anhand der tatsächlichen benutzerdefinierten Dataverse-API-Definition.

Name	Type	Description
name	string	Der eindeutige (logische) Name der benutzerdefinierten Dataverse-API.
displayName	string	Der Anzeigename einer benutzerdefinierten API.
isFunction	boolean	true wenn die benutzerdefinierte Dataverse-API eine Funktion ist (schreibgeschützt); false wenn es sich um eine Aktion handelt, einschließlich des Zeitpunkts, zu dem dieser Wert zur Bindungszeit nicht aufgezeichnet wurde.
bindingType	string	Der Bindungstyp: "Global" oder "Entity".
boundEntityLogicalName	string	(Optional) Die Tabelle, an die die Aktion oder Funktion gebunden ist, wenn bindingType dies der Zeitpunkt ist "Entity".
parameters	Object[]	Die Eingabeparameter, die aufgezeichnet wurden, als die benutzerdefinierte Dataverse-API an die Seite gebunden wurde, jeweils mit einem und declaredKind.name type ist immer "unknown" und optional immer false – weder spiegelt die tatsächlichen Metadaten der benutzerdefinierten Dataverse-API wider.
outputs	Object[]	Immer ein leeres Array. Die Bindungsermittlung zeichnet keine Ausgabeparameter auf.

listBoundActions Beispiel

const actions = await dataApi.listBoundActions?.();