Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Funktionen sind wiederverwendbare Vorgänge, die Sie mithilfe der Web-API ausführen können. Die Web-API enthält zwei Arten von Funktionen:
Funktionen: Verwenden Sie eine
GETAnforderung 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
Übergeben Sie für Funktionen, die Parameter erfordern, die Werte mithilfe von Parameteraliasen.
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/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)
Einige Probleme können jedoch dazu führen, dass Anforderungen fehlschlagen, es sei denn, Sie senden diese Anforderungen mithilfe von Parameteraliasen:
- Wenn Sie die
400 Bad Request - Invalid URLüberschreiten, wird ein Fehler angezeigt. - 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 mithilfe von Parameteraliasen übergeben, wie im folgenden Codebeispiel gezeigt:
GET /GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033
Wenn Sie einen Parameterwert mehrmals verwenden, ermöglichen Parameter-Aliasse 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:
Wenn Sie einen Verweis auf einen vorhandenen Datensatz übergeben, fügen Sie die @odata.id Anmerkung zum URI für den Datensatz hinzu. Wenn Sie beispielsweise die RetrievePrincipalAccess Funktion verwenden, können Sie den folgenden URI verwenden, um den Zugriff auf einen bestimmten Kontaktdatensatz anzugeben:
GET /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
Sie können nur Funktionen binden, die in Web API Function Reference oder Funktionen gefunden werden, die Sie als benutzerdefinierte API erstellen. 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 SDK für die .NET RetrieveUserPrivilegesRequest-Klasse. In der Web-API ist diese Funktion an den systemuser Entitätstyp gebunden, der das SDK für .NET RetrieveUserPrivilegesRequest.UserId-Eigenschaft darstellt. Anstatt eine Instanz des SDK für .NET RetrieveUserPrivilegesResponse-Klasse zurückzugeben, gibt diese Funktion einen RetrieveUserPrivilegesResponse komplexen Typ zurück. Wenn eine Funktion einen komplexen Typ zurückgibt, wird die Definition in der Regel direkt über der Definition der Funktion im CSDL-$metadata-Dokument 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
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 wird im CSDL-$metadata Dokument 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 SDK für .NET WhoAmIRequest-Klasse und gibt einen WhoAmIResponse komplexen Typ zurück, der dem SDK für .NET WhoAmIResponse-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
Sie können Funktionen auf zwei Arten verwenden, um die von Abfragen zurückgegebenen Daten zu steuern. Mit bestimmten Funktionen können Sie die Spalten oder Bedingungen steuern, die sie zurückgeben. Sie können abfragefunktionen auch 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. Jede dieser Funktionen verfügt über eine entsprechende Nachricht im SDK, die entweder einen ColumnSet-Klasse oder einen QueryBase-Klasse Typparameter aus dem SDK für .NET akzeptiert. Die OData-Systemabfrageoptionen bieten die gleiche Funktionalität, sodass diese Funktionen nicht über dieselben Parameter wie ihre Begleitnachrichten im SDK für .NET verfügen. In der folgenden Tabelle werden zusammensetzbare Funktionen aufgeführt.
Abfragefunktionen
Verwenden Sie die im Web API Query Function Reference aufgeführten Funktionen, um eine Abfrage zu erstellen. 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 /accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12
Einschränkungen von Abfragefunktionen
Eine Einschränkung der 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 /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 /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 /accounts?$select=name&$filter=not Microsoft.Dynamics.CRM.Last7Days(PropertyName=@p1)&@p1='createdon'
Verwenden Sie die OlderThanXDays Abfragefunktion wie folgt:
GET /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)
Web-API-Funktionen und -Aktionen (Beispiel) (PowerShell)
Datenabfrage mit Web-API
Nutzen von Web-API-Aktionen