Utilizzare le funzioni API Web

Data di pubblicazione: gennaio 2017

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Le funzioni e le azioni rappresentano operazioni riutilizzabili che puoi eseguire utilizzando l'API Web. Esistono due tipi di funzioni nell'API Web.

• Funzioni
  Utilizza una richiesta GET con le funzioni elencate in Web API Function Reference per eseguire operazioni senza effetti collaterali. Queste funzioni consentono in genere di recuperare i dati. Vengono restituiti una raccolta o un tipo complesso. Ciascuna di queste funzioni dispone di un messaggio corrispondente nel servizio dell'organizzazione.

• Funzioni di query
  Utilizza le funzioni elencate in Web API Query Function Reference per valutare le proprietà e i valori della composizione di una query. Ciascuna di queste funzioni dispone di un valore ConditionOperator corrispondente.

In questo argomento

Passare i parametri a una funzione

Passare a una funzione il riferimento a un'entità

Funzioni associate e non associate

Comporre una query con le funzioni

Passare i parametri a una funzione

Per le funzioni che richiedono i parametri, la procedura consigliata consiste nel passare i valori utilizzando i parametri. Ad esempio, quando utilizzi GetTimeZoneCodeByLocalizedName Function, devi includere i valori dei parametri LocaleId e LocalizedStandardName. Potresti quindi utilizzare la sintassi inline seguente come illustrato di seguito.

GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

Tuttavia, esiste un problema non risolto utilizzando i valori DateTimeOffset con la sintassi inline, come descritto nel seguente articolo: DateTimeOffset come parametro della query N. 204.

Pertanto, la procedura consigliata consiste nel passare i valori come parametri come illustrato nell'esempio di codice seguente. Se utilizzi questa procedura consigliata, puoi evitare il problema non risolto applicabile a DateTimeOffset.

GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033

Gli alias dei parametri ti consentono inoltre di riutilizzare i valori dei parametri per ridurre la lunghezza complessiva dell'URL quando il valore del parametro viene utilizzato più volte.

Passare a una funzione il riferimento a un'entità

Alcune funzioni richiedono il passaggio di un riferimento a un'entità esistente. Ad esempio, le seguenti funzionalità hanno un parametro che richiede crmbaseentity EntityType

Quando passi un riferimento a un'entità esistente, usa l'annotazione @odata.id sull'URI per l'entità. Ad esempio se usi RetrievePrincipalAccess Function puoi utilizzare il seguente URI per specificare il recupero dell'accesso a un contatto specifico:

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)'} 

L'annotazione @odata.id può essere l'URI completo o anche l'URI relativo.

Funzioni associate e non associate

Possono essere associate solo le funzioni disponibili in Web API Function Reference. Le funzioni di query non sono mai associate.

Funzioni associate

In d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl, quando un elemento Function rappresenta una funzione associata, il relativo attributo IsBound contiene il valore true. Il primo elemento Parameter definito all'interno della funzione rappresenta l'entità a cui è associata la funzione. Quando l'attributo Type del parametro è una raccolta, la funzione è associata a una raccolta di entità. Ad esempio, la seguente è la definizione della CalculateTotalTimeIncident Function e del CalculateTotalTimeIncidentResponse ComplexType nel linguaggio CSDL.

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

Questa funzione associata è equivalente all'oggetto CalculateTotalTimeIncidentRequest utilizzato dal servizio dell'organizzazione. Nell'API Web questa funzione è associata all'oggetto incident EntityType che rappresenta la proprietà CalculateTotalTimeIncidentRequest.IncidentId. Anziché restituire CalculateTotalTimeIncidentResponse, questa funzione restituisce CalculateTotalTimeIncidentResponse ComplexType. Quando una funzione restituisce un tipo complesso, la relativa definizione viene visualizzata direttamente sopra la definizione della funzione nel linguaggio CSDL.

Per richiamare una funzione associata, aggiungi il nome completo della funzione all'URL e includi tutti i parametri denominati all'interno delle parentesi che seguono il nome della funzione. Il nome completo della funzione include lo spazio dei nomi Microsoft.Dynamics.CRM. Le funzioni non associate non devono utilizzare il nome completo.

Nell'esempio seguente viene illustrato un esempio sull'utilizzo di CalculateTotalTimeIncident Function, che è associato all'entità di incidente.

• Richiesta

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

• Risposta

  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
  }
  

Funzioni non associate

WhoAmI Function non è associata a un'entità. È definita nel linguaggio CSDL senza un attributo IsBound.

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

Questa funzione corrisponde a WhoAmIRequest e restituisce un WhoAmIResponse ComplexType che corrisponde a WhoAmIResponse utilizzato dal servizio di organizzazione. Questa funzione non presenta alcun parametro.

Quando richiami una funzione non associata, utilizza solo il nome della funzione come illustrato nell'esempio seguente.

• Richiesta

  GET cc_WebAPI_ServiceURI/WhoAmI() HTTP/1.1
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• Risposta

  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"
  }
  

Comporre una query con le funzioni

Vi sono due modi per utilizzare le funzioni per controllare i dati restituiti di controllo con le query. Alcune funzioni consentono di controllare le colonne o le condizioni da esse restituite mentre utilizzi le funzioni di query per valutare le condizioni in una query.

Funzioni componibili

Alcuni funzioni elencate in Web API Function Reference restituiranno una raccolta di entità. Un sottoinsieme di queste funzionalità è componibile, che significa che puoi includere un'opzione query di sistema $filter o $select aggiuntiva per controllare quali colonne vengono restituite nei risultati. Queste funzioni presentano un attributo IsComposable nel linguaggio CSDL. Ciascuna di queste funzione presenta un messaggio complementare nel servizio dell'organizzazione che accetta un parametro di tipo ColumnSet o QueryBase. Le opzioni query di sistema OData offrono le stesse funzionalità, quindi tali funzioni non presentano gli stessi parametri dei relativi messaggi complementari nel servizio nell'organizzazione. Nella tabella seguente è riportato un elenco delle funzioni componibili di questa versione.

Funzioni di query

Le funzioni elencate in Web API Query Function Reference devono essere utilizzate per comporre una query. Queste funzioni possono essere utilizzare in modo analogo alle Funzionalità di query standard, ma esistono alcune differenze importanti.

Devi utilizzare il nome completo della funzione e includere i nomi dei parametri. Nell'esempio seguente viene illustrato come utilizzare LastXHours Function per restituire tutte le entità account modificate nelle ultime 12 ore.

GET cc_WebAPI_ServiceURI/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

Vedere anche

Esempio di azioni e funzioni API Web (C#)
Esempio di azioni e funzioni API Web (JavaScript lato client)
Eseguire operazioni tramite l'API Web
Comporre richieste HTTP e gestire gli errori
Query di dati tramite l'API Web
Creare un'entità utilizzando l'API Web
Recupera un'entità utilizzando l'API Web
Aggiorna ed elimina le entità con l'API Web
Associa e annulla associazione entità con l'API Web
Utilizzare le azioni API Web
Eseguire operazioni in batch usando l'API Web
Rappresentare un altro utente usando l'API Web
Eseguire operazioni condizionali tramite l'API Web

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright