Nutzen von Web-API-Funktionen

Artikel
02/23/2023
3 Minuten Lesedauer

Hinweis

Unsicher bei Entität vs. Tabelle? Siehe Developers: Understand terminology in Microsoft Dataverse.

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.

Ü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önnten also die im Folgenden gezeigte Inlinesyntax 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.

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 [Organization URI]/api/data/v9.0/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.

Referenz auf einen Datensatz an eine Funktion übergeben

Bestimmte Funktionen benötigen das Übergeben eines Verweises auf einen vorhandenen Datensatz. Beispielsweise haben die folgenden Funktionen einen Parameter, der einen crmbaseentity-Entitätstyp erfordert:

Funktionen
CalculateRollupField	IncrementKnowledgeArticleViewCount	InitializeFrom
IsValidStateTransition	RetrieveDuplicates	RetrieveLocLabels
RetrievePrincipalAccess	RetrieveRecordWall	ValidateRecurrenceRule

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 den folgenden URI verwenden, um den Zugriff auf einen bestimmten Datensatz festzulegen:

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 @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 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.

Als Beispiel folgt 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 vom Organisationsdienst verwendeten Klasse RetrieveUserPrivilegesRequest. In der Web-API ist diese Funktion an den Entitätstyp systemuser gebunden, der für die Eigenschaft RetrieveUserPrivilegesRequest.UserId steht. 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. Beziehen Sie alle benannten Parameter 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 mit der Funktion RetrieveUserPrivileges, die an die Tabelle systemuser gebunden ist.

Anfordern

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

Response

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. 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 der Klasse WhoAmIRequest und gibt einen komplexen Typ WhoAmIResponse zurück, der der vom Organisationsdienst verwendeten Klasse WhoAmIResponse entspricht. 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, 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.

Funktionen
RetrieveAllChildUsersSystemUser	RetrieveBusinessHierarchyBusinessUnit	RetrieveUnpublishedMultiple
SearchByBodyKbArticle	SearchByKeywordsKbArticle	SearchByTitleKbArticle

Abfragefunktionen

In Web API Query Function Reference aufgeführte Funktionen sind für das Verfassen einer Abfrage vorgesehen. Diese Funktionen können ähnlich wie die Integrierte Abfragefunktionen 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, wie Sie die LastXHours-Abfragefunktion verwenden, um alle Kontoentitäten 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 besteht darin, dass Sie den Operator not nicht verwenden können, um Abfragefunktionen zu negieren.

Beispielsweise schlägt die folgende Abfrage mit der Abfragefunktion EqualUserId aufgrund des folgenden Fehlers 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. Sie können zum Beispiel die Abfragefunktion NotEqualUserId verwenden. Die folgende Abfrage liefert die erwarteten Ergebnisse:

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. Gehen Sie beispielsweise folgendermaßen vor, wenn Sie die Abfragefunktion Last7Days nicht auf diese Weise negieren möchten (was aufgrund des genannten Fehlers 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#)
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 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
Web-API-Aktionen verwenden
Ausführen von Batchbetrieben mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit Web API
Bedingte Vorgänge mithilfe der Web-API ausführen