Nutzen von Web-API-Funktionen
Funktionen sind wiederverwendbare Vorgänge, die Sie über die Web-API ausführen können. Es gibt zwei Arten von Funktionen im Web API:
Funktionen: Verwenden Sie eine
GET-Abfrage mit den unter Web API Function Reference aufgeführten Funktionen, um Vorgänge auszuführen, die keine Nebeneffekte haben. Diese Funktionen rufen im Allgemeinen Daten ab, entweder eine Sammlung oder einen komplexen Typ. Für jede Funktion gibt es eine entsprechende Nachricht im Organisationsdienst.Abfragefunktionen: Verwenden Sie die in Web API Query Function Reference aufgeführten Funktionen, um Eigenschaften und Werte in der Zusammensetzung einer Abfrage auszuwerten. Jede Abfragefunktion hat einen entsprechenden ConditionOperator-Wert.
Übergeben von Parametern an eine Funktion
Für Funktionen, die Parameter benötigen, wird empfohlen, die Werte mithilfe von Parametern zu übergeben.
Wenn Sie zum Beispiel die Funktion GetTimeZoneCodeByLocalizedName verwenden, müssen die Parameterwerte LocalizedStandardName und LocaleId eingeschlossen werden. Sie können die folgende Inline-Syntax verwenden:
GET [Organization URI]/api/data/v9.0/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)
Es gibt jedoch ein Problem bei der Verwendung von DateTimeOffset-Werten mit der Inline-Syntax, wie im folgenden Artikel erläutert: DateTimeOffset als Abfrageparameter #204.
Umgehen Sie das DateTimeOffset-Problem, indem Sie die Werte als Parameter übergeben, wie im folgenden Codebeispiel gezeigt:
GET [Organization URI]/api/data/v9.0/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033
Wenn ein Parameterwert mehrfach verwendet wird, können Sie ihn mithilfe von Parameteraliasen wiederverwenden, um die Länge der URL zu reduzieren.
Referenz auf einen Datensatz an eine Funktion übergeben
Bestimmte Funktionen erfordern die Übergabe eines Verweises auf einen vorhandenen Datensatz. Beispielsweise haben die folgenden Funktionen einen Parameter, der einen crmbaseentity-Entitätstyp erfordert:
Wenn Sie einen Verweis an einen vorhandenen Datensatz übergeben, verwenden Sie die @odata.id-Anmerkung zum URI für den Datensatz. Wenn Sie zum Beispiel die Funktion RetrievePrincipalAccess verwenden, können Sie die folgende Uri verwenden, um den Zugriff auf einen bestimmten Datensatz anzugeben:
GET [Organization URI]/api/data/v9.0/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'}
Die Anmerkung @odata.id kann entweder die vollständige URI oder eine relative URI sein.
Gebundene und ungebundene Funktionen
Nur Funktionen, die in Web API Function Reference gefunden oder als Custom-API erstellt wurden, dürfen gebunden werden. Abfragefunktionen sind nie gebunden.
Gebundene Funktionen
Wenn im CSDL $metadata-Dokument ein Function-Element eine gebundene Funktion darstellt, enthält 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.
Das folgende Beispiel ist die Definition der Funktion RetrieveUserPrivileges und des komplexen Typs RetrieveUserPrivilegesResponse in der CSDL.
<ComplexType Name="RetrieveUserPrivilegesResponse">
<Property Name="RolePrivileges" Type="Collection(mscrm.RolePrivilege)" />
</ComplexType
<Function Name="RetrieveUserPrivileges" IsBound="true">
<Parameter Name="entity" Type="mscrm.systemuser" Nullable="false" />
<ReturnType Type="mscrm.RetrieveUserPrivilegesResponse" Nullable="false" />
</Function>
Diese gebundene Funktion entspricht der Klasse RetrieveUserPrivilegesRequest, die vom SDK für .NET verwendet wird. In der Web-API ist diese Funktion an den Typ systemuser gebunden, der die Eigenschaft RetrieveUserPrivilegesRequest.UserId darstellt. Anstatt eine Instanz der Klasse RetrieveUserPrivilegesResponse zurückzugeben, gibt diese Funktion einen komplexen Typ RetrieveUserPrivilegesResponse zurück. Wenn eine Funktion einen komplexen Typ zurückgibt, erscheint ihre Definition normalerweise direkt über der Definition der Funktion in der CSDL.
Um eine gebundene Funktion aufzurufen, hängen Sie den vollständigen Namen der Funktion an die URL an und fügen alle benannten Parameter in Klammern nach dem Funktionsnamen 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
Rufen Sie eine gebundene Funktion über einen URI auf, um den ersten Parameterwert zu setzen. Sie können es nicht als Parameterwert mit Namen festlegen.
Das folgende Beispiel verwendet die Funktion RetrieveUserPrivileges, die an die Tabelle systemuser gebunden ist.
Anforderung:
GET [Organization URI]/api/data/v9.2/systemusers(da455fec-68b7-ec11-9840-000d3a13d713)/Microsoft.Dynamics.CRM.RetrieveUserPrivileges HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Antwort:
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v8.2/$metadata#Microsoft.Dynamics.CRM.RetrieveUserPrivilegesResponse",
"RolePrivileges": [
{
"Depth": "Global",
"PrivilegeId": "20db4bf7-60c4-4eb9-ab95-0949766fef1a",
"BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
"PrivilegeName": "prvCreateflowsession"
},
{
"Depth": "Global",
"PrivilegeId": "d8db8e4c-5b76-48eb-b5ec-171b8c661917",
"BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
"PrivilegeName": "prvWriteworkflowbinary"
},
... <full list of privileges removed for brevity>
{
"Depth": "Global",
"PrivilegeId": "b234db9f-27a2-4d12-8b51-fc34fbef9d87",
"BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
"PrivilegeName": "prvWriteflowsession"
}
]
}
Ungebundene Funktionen
Die Funktion WhoAmI ist nicht an eine Entität gebunden. Er ist in der CSDL ohne ein 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 der Klasse WhoAmIRequest und gibt einen komplexen Typ WhoAmIResponse zurück, der der Klasse WhoAmIResponse entspricht, die vom SDK für .NET 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 [Organization URI]/api/data/v9.0/WhoAmI() HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Antwort:
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.0/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
"BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1",
"UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1",
"OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1"
}
Eine Abfrage mit Funktionen verfassen
Es gibt zwei Möglichkeiten, Funktionen zur Steuerung der mit Abfragen zurückgegebenen Daten zu verwenden. Bestimmte Funktionen lassen die Kontrolle über die Spalten oder Bedingungen zu, die sie zurückgeben, und Sie können Abfragefunktionen verwenden, um Bedingungen in einer Abfrage auszuwerten.
Verfassbare Funktionen
Einige der in Web API Function Reference aufgeführten Funktionen geben eine Sammlung von Entitäten zurück. Eine Teilmenge dieser Funktionen ist komponierbar, d.h. Sie können eine $select- oder $filter-Systemabfrageoption einfügen, um zu steuern, welche Spalten in den Ergebnissen zurückgegeben werden. Diese Funktionen haben ein IsComposable-Attribut im CDSL. Für jede dieser Funktionen gibt es eine entsprechende Nachricht im SDK, die entweder einen Parameter vom Typ ColumnSet oder QueryBase akzeptiert. Die OData-Systemabfrageoptionen bieten dieselbe Funktionalität, sodass diese Funktionen nicht dieselben Parameter haben wie ihre entsprechenden Nachrichten im SDK. Die folgende Tabelle enthält eine Liste dieser zusammensetzbaren Funktionen in dieser Version.
| Funktionen | ||
|---|---|---|
| RetrieveAllChildUsersSystemUser | RetrieveBusinessHierarchyBusinessUnit | RetrieveUnpublishedMultiple |
| SearchByBodyKbArticle | SearchByKeywordsKbArticle | SearchByTitleKbArticle |
Abfragefunktionen
Die unter Web API Query Function Reference aufgeführten Funktionen sind dazu gedacht, eine Abfrage zusammenzustellen. Sie können sie auf ähnliche Weise wie die OData-Abfragefunktionen verwenden, es gibt jedoch einige wichtige Unterschiede. Sie müssen den vollständigen Namen der Funktion eingeben und die Parameternamen mit einschließen.
Das folgende Beispiel verwendet die Abfragefunktion LastXHours, um alle Entitäten des Kontos zurückzugeben, die in den letzten 12 Stunden geändert wurden:
GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12
Einschränkungen der Abfragefunktionen
Eine der Einschränkungen von Abfragefunktionen ist, dass Sie den Operator not nicht verwenden können, um Abfragefunktionen zu negieren.
Die folgende Abfrage zum Beispiel, die EqualUserId verwendet, schlägt mit der Fehlermeldung fehl: Not operator along with the Custom Named Condition operators is not allowed.
GET [Organization URI]/api/data/v9.1/systemusers?$select=fullname,systemuserid&$filter=not Microsoft.Dynamics.CRM.EqualUserId(PropertyName=@p1)&@p1='systemuserid'
Mehrere Abfragefunktionen verfügen über eine ergänzende negierte Abfragefunktion. Beispiel: NotEqualUserId negiert EqualUserId, sodass die folgende Abfrage die erwarteten Ergebnisse liefert:
GET [Organization URI]/api/data/v9.1/systemusers?$select=fullname,systemuserid&$filter=Microsoft.Dynamics.CRM.NotEqualUserId(PropertyName=@p1)&@p1='systemuserid'
Andere Abfragefunktionen können auf unterschiedliche Weise negiert werden. Anstatt zu versuchen, die Last7Days Abfragefunktion wie hier zu negieren (was mit dem gleichen Fehler wie oben beschrieben fehlschlägt):
GET [Organization URI]/api/data/v9.1/accounts?$select=name&$filter=not Microsoft.Dynamics.CRM.Last7Days(PropertyName=@p1)&@p1='createdon'
Verwenden Sie die Abfragefunktion OlderThanXDays wie folgt:
GET [Organization URI]/api/data/v9.1/accounts?$select=name&$filter=Microsoft.Dynamics.CRM.OlderThanXDays(PropertyName=@p1,PropertyValue=@p2)&@p1='createdon'&@p2=7
Siehe auch
Web-API-Funktionen und -Aktionen Beispiel (C#)
Web-API-Funktionen und -Aktionen Beispiel (Client-seitiges JavaScript)
Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen erstellen und Fehler behandeln
Abfragen von Daten mithilfe der Web-API
Erstellen einer Tabellenzeile über die Web-API
Abrufen einer Tabellenzeile über die Web-API
Aktualisieren und Löschen von Tabellenzeilen über die Web-API
Zuordnen und Aufheben der Zuordnung von Tabellenzeilen über die 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
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).