Nutzen von Web-API-Funktionen
Veröffentlicht: Januar 2017
Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Funktionen und Aktionen stellen wiederverwendbare Vorgänge dar, die Sie mithilfe der Web-API ausführen können. Es gibt zwei Arten von Funktionen im Web API:
Funktionen
Nutzen Sie eine GET-Anforderung mit den Funktionen, die in Web API Function Reference aufgeführt sind, um Vorgänge ausführen, die keine Nebenwirkungen haben. Diese Funktionen rufen üblicherweise Daten ab. Sie geben entweder eine Sammlung oder einen komplexen Typ zurück. Jede der Funktionalitäten verfügt über eine entsprechende Meldung im Organisationsservice.Abfragefunktionen
Verwenden Sie die in Web API Query Function Reference aufgeführten Funktionen, um die Eigenschaften und Werte in einer Abfrage auswerten. Jede dieser Funktionalitäten verfügt über einen entsprechenden ConditionOperator-Wert.
In diesem Thema
Übergeben von Parametern an eine Funktion
Verweis auf eine Entität an eine Funktion übergeben
Gebundene und ungebundene Funktionen
Verfassen Sie Sie eine Abfrage mit Funktionen
Übergeben von Parametern an eine Funktion
Für Funktionen, die Parameter benötigen, wird empfohlen, die Werte mithilfe von Parametern zu übergeben. Wenn Sie z. B. GetTimeZoneCodeByLocalizedName Function verwenden, müssen die Parameterwerte LocalizedStandardName und LocaleId enthalten sein. Sie könnten also die im Folgenden gezeigte Inlinesyntax verwenden.
GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)
Es gibt jedoch ein offenes Problem bei der Verwendung von DateTimeOffset-Werten mit der Inlinesyntax, wie im Artikel erläutert: DateTimeOffset als Abfrageparameter 204.
Daher wird empfohlen, die Werte als Parameter zu übergeben, wie im folgenden Codebeispiel zu sehen. Wenn Sie diese bewährte Methode verwenden, können Sie das offene Problem vermeiden, das für DateTimeOffset gilt.
GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033
Parameteraliase ermöglichen auch die Wiederverwendung von Parameterwerten, um die Gesamtlänge der URL zu verringern, wenn der Parameterwert mehrmals verwendet wird.
Verweis auf eine Entität an eine Funktion übergeben
Bestimmte Funktionen benötigen das Übergeben eines Verweises auf eine vorhandene Entität. Beispielsweise verfügen die folgenden Funktionen über einen Parameter, der einen crmbaseentity EntityType benötigt.
Wenn Sie einen Verweis an eine vorhandene Entität übergeben, verwenden Sie die @odata.id-Anmerkung zum URI für die Entität. Angenommen Sie verwenden die RetrievePrincipalAccess Function, können Sie folgenden URI verwenden, um das Abrufen des Zugriffs zu einem bestimmten Kontakt anzugeben:
GET cc_WebAPI_ServiceURI/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'}
Die @odata.id-Anmerkung kann der vollständige URI sein, aber ein relativer URI funktioniert auch.
Gebundene und ungebundene Funktionen
Es können nur die Funktionen in Web API Function Reference gebunden werden. Abfragefunktionen sind niemals gebunden.
Gebundene Funktionen
Im d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl, wenn ein Function-Element eine gebundene Funktion darstellt, besitzt es ein IsBound-Attribut mit dem Wert true. Das erste Parameter-Element innerhalb der Funktion repräsentiert die Entität, an die die Funktion geknüpft ist. Wenn das Attribut Type des Parameters eine Sammlung ist, wird die Funktion an eine Entitätssammlung gebunden. Als Beispiel wird die folgende Definition der CalculateTotalTimeIncident Function und CalculateTotalTimeIncidentResponse ComplexType in der CSDL dargestellt.
<ComplexType Name="CalculateTotalTimeIncidentResponse">
<Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
<Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
<ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>
Diese Bindungsfunktion ähnelt CalculateTotalTimeIncidentRequest, was vom Organisationsservice verwendet wird. In der Web-API ist diese Funktion an den incident EntityType gebunden, der die CalculateTotalTimeIncidentRequestIncidentId-Eigenschaft darstellt. Anstatt eine CalculateTotalTimeIncidentResponse zurückzugeben, gibt diese Funktion eine CalculateTotalTimeIncidentResponse ComplexType zurück. Gibt eine Funktion einen komplexen Datentyp zurück, so wird dessen Definition direkt über der Definition der Funktion in CSDL angezeigt.
Um eine gebundene Funktion aufzurufen, hängen Sie den vollständigen Namen der Funktion an die URL. Beziehen Sie alle benannten Paramter in den Klammer nach dem Funktionsnamen mit ein. Der vollständige Funktionsname enthält den Namespace Microsoft.Dynamics.CRM. Für nicht gebundene Funktionen das nicht der vollständige Name verwendet werden.
Wichtig
Eine Funktion muss mithilfe einer URI aufgerufen werden, um den ersten Parameterwert festzulegen. Sie können es nicht als Parameterwert mit Namen festlegen.
Das folgende Beispiel zeigt ein Beispiel mittels CalculateTotalTimeIncident Function, das an die Vorfallentität gebunden ist.
Anforderung
GET cc_WebAPI_ServiceURI/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1 Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0Antwort
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context":"cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse","TotalTime":30 }
Ungebundene Funktionen
Der WhoAmI Function ist nicht an eine Entität gebunden. Es wird in CSDL ohne IsBound-Attribut definiert.
<ComplexType Name="WhoAmIResponse">
<Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
<Property Name="UserId" Type="Edm.Guid" Nullable="false" />
<Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
<Function Name="WhoAmI">
<ReturnType Type="mscrm.WhoAmIResponse" Nullable="false" />
</Function>
Diese Funktion entspricht WhoAmIRequest und gibt einen WhoAmIResponse ComplexType zurück, der WhoAmIResponse entspricht, was vom Organisationsservice verwendet wird. Diese Funktion verfügt über keine Parameter.
Wenn Sie eine ungebundene Funktion aufrufen, verwenden Sie nur den Funktionsnamen wie im folgenden Beispiel gezeigt.
Anforderung
GET cc_WebAPI_ServiceURI/WhoAmI() HTTP/1.1 Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0Antwort
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context": "cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse", "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1", "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1", "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1" }
Verfassen Sie Sie eine Abfrage mit Funktionen
Es gibt zwei Möglichkeiten, mit denen Funktionen verwendet werden können, um Daten, die mit Anfragen zurückgesendet werden, zu kontrollieren. Bestimmte Funktionen ermöglichen Kontrolle über die Spalten oder Bedingungen, die sie zurückgeben, und Sie verwenden Abfragefunktionen, um die Bedingungen in einer Abfrage zu evaluieren.
Verfassbare Funktionen
Einige in Web API Function Reference aufgeführte Funktionen, geben eine Sammlung von Einträgen zurück. Eine Teilmenge dieser Funktionen ist zusammensetzbar, das heißt, Sie können eine weitere Systemabfrageoption $select oder $filter einschließen, um zu steuern, welche Spalten in den Ergebnissen zurückgegeben werden. Diese Funktionen haben ein IsComposable-Attribut im CDSL. Jede dieser Funktionen enthält eine Begleitnachricht im Organisationsservice, der entweder einen Parameter vom Typ ColumnSet oder QueryBase akzeptiert. Die OData Systemabfrageoptionen enthalten dieselben Features also haben diese Funktionen nicht die gleichen Parameter wie die Begleitnachrichten im Organisationsservice. Die folgende Tabelle enthält eine Liste dieser zusammensetzbaren Funktionen in dieser Version.
Abfragefunktionen
In Web API Query Function Reference aufgeführte Funktionen sind für das Verfassen einer Abfrage vorgesehen. Diese Funktionen können ähnlich wie Standardabfragenfunktionen verwendet werden, aber es gibt einige wichtige Unterschiede.
Sie müssen den vollständigen Namen der Funktion eingeben und die Parameternamen mit einschließen. Das folgende Beispiel zeigt die Anwendung von LastXHours Function zum Zurückgeben aller Firmenentitäten, die in den letzten 12 Stunden geändert wurden.
GET cc_WebAPI_ServiceURI/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12
Siehe auch
Internet-API-Funktionen- und Aktionen-Beispiel (C#)
Beispiele von Web API-Funktionen und Aktionen (clientseitiges JavaScript)
Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen verfassen und Fehler beheben
Datenabfrage mit Web-API
Erstellen einer Entität mithilfe des Web-API
Abrufen einer Entität mithilfe des Web-API
Entitäten aktualisieren und löschen mithilfe der Web API
Entitäten zuordnen und Zuordnungen aufheben mithilfe der Web API
Nutzen von Web-API-Aktionen
Ausführen von Batchbetrieben mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit Web API
Bedingte Vorgänge mithilfe der Web-API ausführen
Microsoft Dynamics 365
© 2017 Microsoft. Alle Rechte vorbehalten. Copyright