Web-API-Funktionen

Artikel
08/24/2023

Im CSDL $metadata-Dokument befinden sich Function-Elemente. Funktionsvorgänge unterscheiden sich darin von Aktionen, da sie keine Daten ändern sollten. Sie werden normalerweise nur zum Abrufen von Daten verwendet.

Jede Funktion enthält ein Name-Attribut. Dieser Name wird Teil der URL sein, wenn Sie HTTP``GET verwenden, wobei alle definierten Parameter für die Funktion in der URL der Anfrage gesendet werden.

Gebundene Funktionen

Wie Aktionen können Funktionen ein IsBound="true"-Attribut enthalten. Dies bedeutet, dass es sich um eine gebundene Funktion handelt. Funktionen ohne das Attribut IsBound sind ungebunden. Eine gebundene Funktion bedeutet, dass der erste Parameter ein Verweis auf einen Tabellendatensatz oder auf ein Entitätsset ist.

Wenn eine Funktion gebunden ist, enthält sie einen Verweis auf ein bestimmtes Element im Service-Namespace. Um die Funktion zu verwenden, geben Sie den vollqualifizierten Namen mit dem Namespace Microsoft.Dynamics.CRM ein. Weitere Informationen: Service-Namespace

Verfassbare Funktionen

Funktionen können ein IsComposable="true"-Attribut enthalten. Dies bedeutet, dass Sie einige Systemabfrageoptonen wie $filter oder $select an die URL anhängen können, um die zurückgegebenen Ergebnisse anzugeben. Diese Option ist nur für bestimmte Systemfunktionen verfügbar. Sie können mit Custom-API keine Funktion erstellen, die zusammensetzbar ist.

Parameter

Funktionen haben normalerweise ein oder mehrere Parameter-Elemente. Jeder Parameter hat die folgenden Attribute:

Attribut	Beschreibung
`Name`	Der Name des Parameters. Der Name ist eindeutig, es sei denn, die `Function` ist überlastet. Weitere Informationen finden Sie unter Überlastete Funktionen.
`Type`	Der Typ von Parameter.
`Nullable="false"`	Ob der Parameter einen Nullwert akzeptieren kann

ReturnType

Funktionen müssen Werte zurückgeben. Eine Funktion hat immer ein ReturnType-Element.

Attribut	Beschreibung
`Type`	Der Typ von Parameter.
`Nullable="false"`	Ob der Wert null sein darf.

Beispiele für Funktionsdefinitionen

Es folgen einige fiktive Beispiele der Function-Definitionen, die unterschiedliche Bindungsmuster zeigen. Jedes dieser Beispiele gibt einen ganzzahligen Wert zurück.

Ungebundene Funktionen

Eine ungebundene Funktion mit einem einzelnen ganzzahligen Number-Parameter.

<Function Name="UnBoundFunctionExample">
    <Parameter Name="Number" Type="Edm.Int32" Nullable="false" />
    <ReturnType Type="Edm.Int32" Nullable="false" />
</Function>

An eine Entität gebundene Funktion

Eine an die account-Entität gebundene Funktion mit einem einzelnen ganzzahligen Number-Parameter.

<Function Name="EntityBoundFunctionExample" IsBound="true">
    <Parameter Name="entity" Type="mscrm.account" Nullable="false" />
    <Parameter Name="Number" Type="Edm.Int32" Nullable="false" />
    <ReturnType Type="Edm.Int32" Nullable="false" />
</Function>

An ein Entitätsset gebundene Funktion

Eine an das account-Entitätsset gebundene Funktion mit einem einzelnen ganzzahligen Number-Parameter.

<Function Name="EntityCollectionBoundFunctionExample" IsBound="true">
    <Parameter Name="entityset" Type="Collection(mscrm.account)" Nullable="false" />
    <Parameter Name="Number" Type="Edm.Int32" Nullable="false" />
    <ReturnType Type="Edm.Int32" Nullable="false" />
</Function>

Überladene Funktionen

Normalerweise ist jede in $metadaten gefundene Funktion die einzige Funktion mit diesem Namen. Gebundene Funktionen können jedoch mehrere Definitionen haben, wenn sie an verschiedene Typen gebunden sind. Die Systemfunktionen RetrieveUnpublished und RetrieveUnpublishedMultiple sind Beispiele. Sie können keine überladene Funktion mit angepasster API erstellen.

Weitere Informationen finden Sie unter OData 4.0 Regeln für überladene Aktionen.

Nächste Schritte

Weitere Informationen zu Complex- und Enum-Typen.

Komplexe Typen und Enumerationstypen

Siehe auch

Dataverse-Web API verwenden
Internet API-Typen und -Vorgänge
Web API-Servicedokumente
Web API Entitätstypen
Web API-Eigenschaften
Navigationseigenschaften der Web API
Web API-Aktionen
Komplexe Typen und Enumerationstypen (Web API)
OData-Version 4.0 Teil 3: Common Schema Definition Language (CSDL) Plus Errata 03 Element edm:Function

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).

Freigeben über