Dataverse-åtgärder och funktionsmetoder för generativa sidor

Använd åtgärden och funktionsmetoderna för dataApi objektet för att anropa anpassade API:er för Dataverse som är bundna till sidan.

Note

Åtgärds- och funktionsmetoder är valfria i det delade dataApi kontraktet. Vissa värdar implementerar dem inte, så kontrollera att det finns en metod innan du anropar den. En metod som finns innebär inte att åtgärden är bunden till sidan, aktiverad för körningen eller tillåten för den aktuella användaren. Till skillnad från anslutningsmetoder genererar dessa metoder aldrig för förväntade fel. de löser med ok: false och en felkod i stället. Hantera resultatets ok och error egenskaperna explicit.

listBoundActions returnerar de åtgärder och funktioner som den aktuella körningskonfigurationen tillåter för sidan när identifieringen är aktiverad. Det är inte en garanti för att den aktuella användaren har de Dataverse-behörigheter som krävs för att köra varje angiven åtgärd.

Method	Description
executeAction	Anropar ett anpassat API för Dataverse som är bundet till sidan som en åtgärd.
executeFunction	Anropar ett anpassat API för Dataverse som är bundet till sidan som en funktion.
listBoundActions	Visar en lista över anpassade API:er för Dataverse (åtgärder och funktioner) som är bundna till sidan.

executeAction metod

Anropar ett anpassat API för Dataverse som en tillverkare är bunden till sidan som en åtgärd (ett meddelande som kan ändra data).

Parameters

Ange ett värde för den här obligatoriska parametern.

Name	Type	Description
request	DataverseActionRequest	Åtgärden för att anropa och dess indataparametrar.

DataverseActionRequest

Name	Type	Description
name	string	Det unika namnet på det anpassade API:et, publisher-prefix, till exempel new_ApproveExpenseReport.
parameters	object	(Valfritt) De indataparametrar som krävs av åtgärden, med ett unikt parameternamn.
boundTo	object	(Valfritt) En målradsreferens (entityName och id) för entitetsbundna åtgärder. Utelämna globala (obundna) åtgärder.

Returns

Ett löfte som innehåller en DataverseActionResult. Den här metoden genererar aldrig förväntade fel (till exempel ett 403-behörighetsfel, en 400 felaktig parameter eller åtgärden som inte är bunden eller aktiverad) – kontrollera ok egenskapen i stället.

DataverseActionResult

Name	Type	Description
ok	boolean	Anger om åtgärden lyckades.
status	number	HTTP-statuskoden som returneras av Dataverse eller 0 när ingen HTTP-status är tillgänglig. En 0 status kan innebära att körningen avvisade anropet innan det skickades (till exempel not_enabled, , not_boundnot_permitted, wrong_operation_kind, invalid_parametereller invalid_bound_to), att begäran misslyckades utan ett HTTP-svar, eller att resultatet är okänt (indeterminate är true). Använd error.code och indeterminate för att skilja dessa fall åt.
outputs	object	Utdataparametrarna som returneras av åtgärden, med ett unikt namn. Tom för åtgärder utan utdata.
indeterminate	boolean	(Valfritt) true när en timeout eller något annat fel efter sändningen innebär att servern kan ha utfört åtgärden. försök inte igen automatiskt.
error	object	(Valfritt) Felinformation när ok är false, inklusive en maskinläsbar code och en sanerad message. codeär en av not_enabled, not_bound, not_permitted, wrong_operation_kindinvalid_parameter, invalid_bound_to, , indeterminateeller network, eller åtgärdens HTTP-statuskod som en sträng (till exempel "404") när Dataverse returnerade ett felsvar eller "0" när ingen HTTP-status var tillgänglig. not_permitted innebär att åtgärden eller funktionen inte finns i miljöns lista över tillåtna för generativa sidor – den anger inte om den aktuella användaren har behörigheten Dataverse för att köra den. Ett behörighetsfel visas vanligtvis som status: 403 med felkoden "403". Om värden inte kan fastställa HTTP-statusen returneras status: 0 den i stället.

executeAction-exempel

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 metod

Anropar ett anpassat API för Dataverse som en tillverkare som är bunden till sidan som en funktion (ett skrivskyddat meddelande med GET-semantik).

Parameters

Ange ett värde för den här obligatoriska parametern.

Name	Type	Description
request	DataverseFunctionRequest	Funktionen som ska anropas och dess indataparametrar.

DataverseFunctionRequest

Name	Type	Description
name	string	Det unika namnet på det anpassade API:et, publisher-prefix, till exempel new_GetExchangeRate.
parameters	object	(Valfritt) De indataparametrar som krävs av funktionen, med ett unikt parameternamn.
boundTo	object	(Valfritt) En målradsreferens (entityName och id) för entitetsbundna funktioner. Utelämna globala (obundna) funktioner.

Returns

Ett löfte som innehåller en DataverseActionResult. Precis som med executeActiongenererar den här metoden aldrig förväntade fel – kontrollera ok egenskapen i stället.

executeFunction-exempel

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 metod

Visar en lista över anpassade API:er för Dataverse (åtgärder och funktioner) som en tillverkare är bunden till sidan.

Parameters

None.

Returns

Ett löfte som innehåller en matris med DataverseActionInfo-poster . Returnerar en tom matris när identifieringen inte är aktiverad för körningen.

DataverseActionInfo

DataverseActionInfo visar vad sidans skapare är bunden till den här åtgärden eller funktionen, inte realtidsmetadata för Dataverse. Använd den inte för att skapa indataformulär eller verifiera utdata – verifiera parameterkrav och utdataformer mot den faktiska anpassade API-definitionen för Dataverse.

Name	Type	Description
name	string	Det unika (logiska) namnet på det anpassade API:et för Dataverse.
displayName	string	Visningsnamnet för ett anpassat API.
isFunction	boolean	true om det anpassade API:et för Dataverse är en funktion (skrivskyddad); false om det är en åtgärd, inklusive när det här värdet inte registrerades vid bindningstiden.
bindingType	string	Bindningstypen: "Global" eller "Entity".
boundEntityLogicalName	string	(Valfritt) Tabellen som åtgärden eller funktionen är bunden till, när bindingType är "Entity".
parameters	Object[]	Indataparametrarna som registrerades när det anpassade API:et dataversum var bundet till sidan, var och en med en name och declaredKind. type är alltid "unknown" och optional är alltid false – varken återspeglar det anpassade API:ets faktiska metadata för Dataverse.
outputs	Object[]	Alltid en tom matris. Bindningsidentifiering registrerar inte utdataparametrar.

listBoundActions Exempel

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