Freigeben über

Verwenden von Web-API-Funktionen

Funktionen sind wiederverwendbare Vorgänge, die Sie mithilfe der Web-API ausführen können. Es gibt zwei Arten von Funktionen in der Web-API:

  • Funktionen: Verwenden Sie eine GET Anforderung mit den funktionen, die in der Web API Function Reference Liste aufgeführt sind, um Vorgänge auszuführen, die keine Nebenwirkungen haben. Diese Funktionen rufen in der Regel Daten ab, entweder eine Auflistung oder einen komplexen Typ. Jede Funktion weist eine entsprechende Nachricht im Organisationsdienst auf.

  • Abfragefunktionen: Verwenden Sie die in der Web API Query Function Reference Liste aufgeführten Funktionen, um Eigenschaften und Werte in der Zusammensetzung einer Abfrage auszuwerten. Jede Abfragefunktion weist einen entsprechenden ConditionOperator Wert auf.

Übergeben von Parametern an eine Funktion

Bei Funktionen, die Parameter erfordern, empfiehlt es sich, die Werte mithilfe von Parameteraliasen zu übergeben.

Wenn Sie beispielsweise die GetTimeZoneCodeByLocalizedName Funktion verwenden, müssen Sie die LocalizedStandardName Werte und LocaleId Parameterwerte einschließen. Sie können die folgende Inlinesyntax verwenden:

GET [Organization URI]/api/data/v9.2/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

Es gibt jedoch einige Probleme, die dazu führen können, dass Anforderungen fehlschlagen, es sei denn, Sie senden diese Anforderungen mithilfe von Parameteraliasen:

  • Wenn Sie die 400 Bad Request - Invalid URL überschreiten, erhalten Sie einen Fehler.
  • Es gibt ein Problem mit DateTimeOffset-Werten mit der Inlinesyntax, wie im folgenden Artikel erläutert: DateTimeOffset als Abfrageparameter #204.

Vermeiden Sie diese Probleme, indem Sie die Werte mit Parameteraliasen übergeben, wie im folgenden Codebeispiel gezeigt:

GET [Organization URI]/api/data/v9.2/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033

Wenn ein Parameterwert mehrmals verwendet wird, ermöglichen Parameter-Aliasnamen es Ihnen, ihn wiederzuverwenden, um die Länge der URL zu verringern.

Übergeben eines Datensatzverweises an eine Funktion

Bestimmte Funktionen erfordern das Übergeben eines Verweises auf einen vorhandenen Datensatz. Die folgenden Funktionen verfügen beispielsweise über einen Parameter, der einen crmbaseentity Entitätstyp erfordert:

Funktionen    
CalculateRollupField IncrementKnowledgeArticleViewCount InitializeFrom
IsValidStateTransition RetrieveDuplicates RetrieveLocLabels
RetrievePrincipalAccess RetrieveRecordWall ValidateRecurrenceRule

Wenn Sie einen Verweis auf einen vorhandenen Datensatz übergeben, verwenden Sie die @odata.id-Annotation zum Uri des Datensatzes. Wenn Sie beispielsweise die RetrievePrincipalAccess Funktion verwenden, können Sie den folgenden URI verwenden, um den Zugriff auf einen bestimmten Kontaktdatensatz anzugeben:

GET [Organization URI]/api/data/v9.2/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(aaaabbbb-0000-cccc-1111-dddd2222eeee)'}

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 Referenceoder als benutzerdefinierte API erstellt wurden, können gebunden sein. Abfragefunktionen sind nie gebunden.

Gebundene Funktionen

Wenn ein Element im CSDL-$metadata DokumentFunction eine gebundene Funktion darstellt, weist es ein IsBound Attribut mit dem Wert true auf. Das erste Parameter in der Funktion definierte Element stellt die Entität dar, an die die Funktion gebunden ist. Wenn das Type Attribut des Parameters eine Auflistung ist, wird die Funktion an eine Entitätssammlung gebunden.

Das folgende Beispiel ist die Definition der RetrieveUserPrivileges-Funktion 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 RetrieveUserPrivilegesRequest Klasse, 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 RetrieveUserPrivilegesResponse Klasse zurückzugeben, gibt diese Funktion einen RetrieveUserPrivilegesResponse komplexen Typ zurück. Wenn eine Funktion einen komplexen Typ zurückgibt, wird ihre Definition in der Regel direkt über der Definition der Funktion in der CSDL angezeigt.

Um eine gebundene Funktion aufzurufen, fügen Sie den vollständigen Namen der Funktion an die URL an, und fügen Sie alle benannten Parameter in Klammern ein, die dem Funktionsnamen folgen. Der name der vollständigen Funktion enthält den Namespace Microsoft.Dynamics.CRM. Funktionen, die nicht gebunden sind, dürfen nicht den vollständigen Namen verwenden.

Von Bedeutung

Rufen Sie eine gebundene Funktion mithilfe eines URI auf, um den ersten Parameterwert festzulegen. Sie können ihn nicht als benannten Parameterwert festlegen.

Im folgenden Beispiel wird die RetrieveUserPrivileges Funktion verwendet, die an die systemuser Tabelle 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 WhoAmI Funktion ist nicht an eine Entität gebunden. Sie ist in der CSDL ohne Attribut IsBound 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 WhoAmIRequest Klasse und gibt einen WhoAmIResponse komplexen Typ zurück, der der WhoAmIResponse vom SDK für .NET verwendeten Klasse entspricht. Diese Funktion hat 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.2/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.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",  
 "BusinessUnitId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",  
 "UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",  
 "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"  
}

Verfassen einer Abfrage mit Funktionen

Es gibt zwei Möglichkeiten, mit denen Funktionen die mit Abfragen zurückgegebenen Daten steuern können. Bestimmte Funktionen ermöglichen die Kontrolle darüber, welche Spalten oder Bedingungen sie zurückgeben, und Sie können Abfragefunktionen verwenden, um Bedingungen in einer Abfrage auszuwerten.

Komponierbare Funktionen

Einige in Web API Function Reference aufgeführte Funktionen geben eine Sammlung von Entitäten zurück. Eine Teilmenge dieser Funktionen kann verfasst werden, was bedeutet, dass Sie eine oder $select eine $filter Systemabfrageoption einschließen können, um zu steuern, welche Spalten in den Ergebnissen zurückgegeben werden. Diese Funktionen verfügen über ein IsComposable Attribut in der CSDL. 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 über dieselben Parameter wie ihre Begleitnachrichten im SDK verfügen. In der folgenden Tabelle ist eine Liste dieser kompositablen Funktionen in dieser Version aufgeführt.

Funktionen    
RetrieveAllChildUsersSystemUser RetrieveBusinessHierarchyBusinessUnit RetrieveUnpublishedMultiple
SearchByBodyKbArticle SearchByKeywordsKbArticle SearchByTitleKbArticle

Abfragefunktionen

In der Web API Query Function Reference Liste aufgeführte Funktionen sollen zum Verfassen einer Abfrage verwendet werden. Sie können sie ähnlich wie die OData-Abfragefunktionen verwenden, aber es gibt einige wichtige Unterschiede. Sie müssen den vollständigen Namen der Funktion verwenden und die Namen der Parameter einschließen.

Im folgenden Beispiel wird die LastXHours Abfragefunktion verwendet, um alle Kontoentitäten zurückzugeben, die in den letzten 12 Stunden geändert wurden:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

Einschränkungen von Abfragefunktionen

Eine der Einschränkungen von Abfragefunktionen besteht darin, dass Sie den not Operator nicht verwenden können, um Abfragefunktionen zu negieren.

Die folgende Abfrage, die EqualUserId verwendet, schlägt fehl und führt zu dem Fehler: Not operator along with the Custom Named Condition operators is not allowed.

GET [Organization URI]/api/data/v9.2/systemusers?$select=fullname,systemuserid&$filter=not Microsoft.Dynamics.CRM.EqualUserId(PropertyName=@p1)&@p1='systemuserid'

Mehrere Abfragefunktionen weisen eine negierte Begleitabfragefunktion auf. So gibt die folgende Abfrage beispielsweise die erwarteten Ergebnisse zurück:For example, NotEqualUserId negates EqualUserId, so the following query returns the expected results:

GET [Organization URI]/api/data/v9.2/systemusers?$select=fullname,systemuserid&$filter=Microsoft.Dynamics.CRM.NotEqualUserId(PropertyName=@p1)&@p1='systemuserid'

Andere Abfragefunktionen können auf unterschiedliche Weise negiert werden. Anstatt beispielsweise zu versuchen, die Last7Days Abfragefunktion wie folgt zu verwerfen (was mit demselben Fehler wie zuvor erwähnt fehlschlägt):

GET [Organization URI]/api/data/v9.2/accounts?$select=name&$filter=not Microsoft.Dynamics.CRM.Last7Days(PropertyName=@p1)&@p1='createdon'

Verwenden Sie die OlderThanXDays Abfragefunktion wie folgt:

GET [Organization URI]/api/data/v9.2/accounts?$select=name&$filter=Microsoft.Dynamics.CRM.OlderThanXDays(PropertyName=@p1,PropertyValue=@p2)&@p1='createdon'&@p2=7

Siehe auch

Beispiel für Web-API-Funktionen und -Aktionen (C#)
Beispiel für Web-API-Funktionen und -Aktionen (clientseitiges JavaScript)
Ausführen von Vorgängen mithilfe der Web-API
HTTP-Anforderungen erstellen und Fehlern behandeln
Datenabfrage mit Web-API
Erstellen einer Tabellenzeile mithilfe der Web-API
Abrufen einer Tabellenzeile über die Web-API
Tabellenzeilen über die Web-API aktualisieren und löschen
Zuordnen und Aufheben der Zuordnung von Tabellenzeilen über die Web-API
Nutzen von Web-API-Aktionen
Ausführen von Batchvorgängen mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit der Web-API
Bedingte Vorgänge mithilfe der Web-API ausführen

  • Last updated on