Tipi e operazioni API Web

Data di pubblicazione: gennaio 2017

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

Per utilizzare l'API Web devi trovare le informazioni su ciò che è disponibile per l'utilizzo. Il servizio si descrive tramite i documenti di metadati e di servizio a cui puoi accedere. Questo argomento introdurrà i concetti importanti e descriverà come puoi trovare le informazioni necessarie utilizzando la documentazione generata dai documenti di metadati e servizi nonché la documentazione dei tipi di entità di sistema, funzionalità e azioni.

In questo argomento

Terminologia

Documenti di servizio

Tipi di entità

Proprietà

Proprietà di navigazione

Azioni

Funzioni

Tipi complessi

Tipi di enumerazione

Terminologia

L'API Web è implementata mediante lo standard OData v4 che utilizza un set specifico di termini che è necessario conoscere.Entity Data Model (EDM) è il modello di dati astratti utilizzato per descrivere i dati esposti da un servizio OData. Nella tabella seguente è presente un elenco di termini selezionati definiti in OData Version 4.0 Part 1: Protocol Plus Errata 02 che è necessario comprendere.

Documenti di servizio

Esistono due documenti di servizio a cui puoi fare riferimento per ulteriori informazioni sull'API Web.

Documento di servizio

La query seguente, immessa nel campo di indirizzo del browser, restituisce il documento di servizio, un elenco completo di tutti i set di entità disponibili per l'organizzazione. Nota che [URI organizzazione] rappresenta l'URL dell'organizzazione.

[URI organizzazione]/api/data/v8.2

I set di entità vengono restituiti sotto forma di matrice JSON. Ogni elemento nella matrice ha tre proprietà come elencate nella tabella.

Queste informazioni possono essere recuperate utilizzando una richiesta GET e possono essere utili per recuperare l'elenco di tutti i set di entità disponibili per utilizzo con il servizio.

Documento di metadati CSDL

Una richiesta GET al seguente URL restituirà un documento Common Schema Definition Language (CSDL) abbastanza grande (più di 3.5 MB) o un documento di metadati che descrive i dati e le operazioni esposti dal servizio.

[URI organizzazione]/api/data/v8.2/$metadata

Questo documento può essere utilizzato come origine dati per generare le classi che forniranno gli oggetti fortemente tipizzati per il servizio. Se invece non utilizzi le classi generate, potresti voler rivedere la documentazione generata da queste informazioni. Il Web API Reference utilizza le informazioni principalmente da questo documento preso da un sistema non personalizzato.

Per ulteriori informazioni su questo documento vedi OData Version 4.0 Part 3: Common Schema Definition Language (CSDL) Plus Errata 02.

Tipi di entità

Il Web API EntityType Reference elenca ognuno dei tipi di entità di sistema esposti all'API Web per l'archiviazione dei dati aziendali. Un tipo di entità è un tipo strutturato denominato con una chiave. Definisce le proprietà e relazioni denominate di un'entità. I tipi di entità potrebbero derivare da una singola ereditarietà da altri tipi di entità.Web API Metadata EntityType Reference elenca ciascuno dei tipi di entità utilizzati per gestire i metadati di sistema. Entrambi sono tipi di entità ma il modo in cui funzionano è diverso. Vedi Utilizzare l'API Web con i metadati di Dynamics 365 per informazioni sull'utilizzo delle entità modello. Ogni tipo di entità viene incluso in un elemento EntityType in CSDL. Di seguito è riportata la definizione di account EntityType da CSDL con le proprietà e le proprietà di navigazione rimosse.

<EntityType Name="account" BaseType="mscrm.crmbaseentity">
  <Key>
    <PropertyRef Name="accountid" />
  </Key>
  <!--Properties and navigation properties removed for brevity-->
  <Annotation Term="Org.OData.Core.V1.Description" String="Business that represents a customer or potential customer. The company that is billed in business transactions." />
</EntityType>

Ogni pagina di riferimento EntityType della documentazione SDK utilizza le informazioni da CSDL o dai metadati per visualizzare le informazioni seguenti quando disponibili.

Rinominare un set di entità

Per impostazione predefinita, il nome del set di entità corrisponde al valore della proprietà EntityMetadata EntityType LogicalCollectionName (EntityMetadataLogicalCollectionName). Se hai un'entità personalizzata che vuoi indirizzare utilizzando un nome diverso di set di entità, puoi aggiornare il valore della proprietà EntityMetadata EntityType EntitySetName (EntityMetadata.EntitySetName) per utilizzare un nome diverso.

Chiavi alternative

Sebbene Microsoft Dynamics 365 tenere conto creare le chiavi alternative, nella chiave primaria verrà gestita nella documentazione Microsoft Dynamics 365 SDK.

Nessuna delle entità di sistema dispone di chiavi alternative definite. Se vengono definite le chiavi alternative per un'entità, verranno incluse nell'elemento EntityType CSDL come Annotation come segue:

<Annotation Term="OData.Community.Keys.V1.AlternateKeys">
  <Collection>
    <Record Type="OData.Community.Keys.V1.AlternateKey">
      <PropertyValue Property="Key">
        <Collection>
          <Record Type="OData.Community.Keys.V1.PropertyRef">
            <PropertyValue Property="Alias" String="key name" />
            <PropertyValue Property="Name" PropertyPath="key name" />
          </Record>
        </Collection>
      </PropertyValue>
    </Record>
  </Collection>
</Annotation>

Le informazioni sulle chiavi alternative possono essere recuperate dai metadati tramite la proprietà di navigazione con valori di raccolta KeysEntityMetadata EntityType tramite l'API Web o la proprietà EntityMetadata.Keys utilizzando il servizio dell'organizzazione.

Tipo di ereditarietà

L'ereditarietà consente la condivisione delle proprietà comuni e la categorizzazione dei tipi di entità in gruppi. Tutti i tipi di entità nell'API Web ereditano da due dei seguenti tipi di entità. Tutti i tipi di entità aziendale ereditano da crmbaseentity EntityType e tutte le entità modello ereditano da crmmodelbaseentity EntityType.

Proprietà

Ogni tipo di entità può avere proprietà dichiarate corrispondenti agli attributi. Nel contenuto di Web API EntityType Reference e Web API Metadata EntityType Reference, le proprietà che vengono ereditate da un tipo di entità di base sono combinate nell'elenco delle proprietà dichiarate per ogni tipo di entità. L'ereditarietà viene indicata nella descrizione di ogni proprietà.

Negli elementi EntityType CSDL ogni proprietà è inclusa in un elemento Property con un valore di attributo Name corrispondente alle proprietà che imposterai nel codice. Il valore di attributo Type specifica il tipo di dati della proprietà. Le proprietà dei tipi di entità aziendali utilizzano in genere i tipi primitivi OData.

Di seguito è riportato un esempio di proprietà account EntityType name definita in CSDL.

<Property Name="name" Type="Edm.String" Unicode="false">
  <Annotation Term="Org.OData.Core.V1.Description" String="Type the company or business name." />
</Property>

La descrizione della proprietà è disponibile in un elemento Annotation con la proprietà dell'attributo TermOrg.OData.Core.V1.Description. Questa descrizione viene presa dal valore di proprietà AttributeMetadata EntityTypeDescription. Non tutte le proprietà hanno una descrizione.

Ogni proprietà può essere calcolata. Questo significa che il valore può essere impostato dal sistema. Questo è specificato in un elemento Annotation con il valore dell'attributo TermOrg.OData.Core.V1.Computed.

Ogni proprietà può inoltre avere limitazioni sulla possibilità di aggiornamento. Questo è definito in un elemento Annotation con il valore dell'attributo TermOrg.OData.Core.V1.Permissions. L'unico set di opzioni è Org.OData.Core.V1.PermissionType/Read che indica che la proprietà è di sola lettura.

Tipi primitivi

OData supporta una vasta gamma di tipi di dati ma Microsoft Dynamics 365 non li utilizza tutti. Nella tabella seguente viene descritto come i tipi di servizio dell'organizzazione Dynamics 365 sono mappati ai tipi primitivi OData.

Proprietà di tipo lookup

Per la maggior parte delle proprietà di navigazione a valore singolo troverai una proprietà di sola lettura calcolata che utilizza la convenzione di denominazione seguente: _<name>_value dove <name> corrisponde al nome della proprietà di navigazione a valore singolo. L'eccezione a questo modello si ha quando un attributo di tipo lookup dell'entità può accettare più tipi di riferimenti di entità. Un esempio comune è come l'attributo customerid dell'entità incident può essere impostato su un riferimento che è un'entità contact o account. Nelle incident EntityTypeSingle-valued navigation properties troverai customerid_account e customerid_contact come proprietà di navigazione a valore singolo per riflettere il cliente associato a un'opportunità. Se imposti una delle proprietà di navigazione a valore singolo, l'altra verrà impostata su null perché entrambe sono associate all'attributo customerid. Nelle incident EntityTypeProperties troverai una proprietà di tipo lookup _customerid_value che contiene lo stesso valore che è impostato per una delle proprietà di navigazione a valore singolo contenente un valore.

In genere, è consigliabile evitare di utilizzare le proprietà di tipo lookup e utilizzare le proprietà corrispondenti di navigazione a valore singolo. Queste proprietà sono state incluse perché possono risultare utili per alcuni scenari di integrazione. Queste proprietà sono di sola lettura e vengono calcolate perché semplicemente rifletteranno le modifiche applicate tramite la proprietà di navigazione a valore singolo corrispondente.

Quando includi le proprietà di tipo lookup in una query, puoi richiedere l'inclusione delle annotazioni che forniscono informazioni aggiuntive sui dati che vengono impostati per gli attributi sottostanti che non sono rappresentati da una proprietà di navigazione a valore singolo.Ulteriori informazioni:Recuperare i dati sulle proprietà di ricerca

Proprietà di navigazione

In OData, le proprietà di navigazione ti consentono di accedere ai dati relativi all'entità corrente. Quando recuperi un'entità puoi scegliere di espandere le proprietà di navigazione per includere i dati correlati. Sono disponibili due tipi di proprietà di navigazione: a valore singolo e con valori di raccolta.

Proprietà di navigazione a valore singolo

Queste proprietà corrispondono agli attributi di tipo lookup che supportano relazioni molti-a.-uno e consentono l'impostazione di un riferimento a un'altra entità. Nell'elemento EntityType CSDL, queste proprietà vengono definite come elemento NavigationProperty con l'attributo Type impostato su un singolo tipo. Di seguito è riportato un esempio di proprietà di navigazione a valore singolo account EntityType createdby in CSDL:

<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby">
 <ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" />
</NavigationProperty>

Ogni proprietà di navigazione che rappresenta una proprietà di navigazione a valore singolo dispone di una proprietà di navigazione a valore di raccolta corrispondente indicata dal valore dell'attributo Partner. Ogni proprietà di navigazione a valore singolo dispone anche di un elemento ReferentialConstraint con il valore dell'attributo Property che rappresenta la proprietà di tipo lookup di sola lettura calcolata utilizzabile per recuperare il valore GUID corrispondente dell'entità correlata.Ulteriori informazioni:Proprietà di tipo lookup

Proprietà di navigazione con valori di raccolta

Queste proprietà corrispondono alle relazioni uno-a-molti o molti-a-molti. Nell'elemento EntityType CSDL, queste proprietà vengono definite come elemento NavigationProperty con l'attributo Type impostato su una raccolta di un tipo. Di seguito è rappresentata la proprietà di navigazione a valore di raccolta Account_Tasksaccount EntityType che rappresenta una relazione uno-a-molti:

<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />

Quando la proprietà di navigazione a valore di raccolta rappresenta una relazione molti-a-molti, il nome della proprietà di navigazione e il nome del partner saranno identici. Di seguito è rappresentata la proprietà di navigazione a valore di raccolta account EntityType accountleads_association che rappresenta una relazione molti-a-molti:

<NavigationProperty Name="accountleads_association" Type="Collection(mscrm.lead)" Partner="accountleads_association" />

La differenza tra le relazioni uno-a-molti e molti-a-molti non sono importanti quando si utilizza l'API Web. Il modo in cui associ le entità è lo stesso indipendentemente dal tipo di relazione. Sebbene le relazioni molti-a-molti utilizzano ancora le entità intersecate dietro le quinte, solo poche entità intersecate di sistema speciali vengono incluse in Web API EntityType Reference. Ad esempio, campaignactivityitem EntityType è tecnicamente un'entità intersecata, ma viene inclusa perché ha più proprietà di un'entità intersecata ordinaria.

Un'entità intersecata ordinaria ha solo le quattro proprietà di base richieste per gestire la relazione molti-a-molti. Quando crei una relazione molti-a-molti personalizzata tra entità, un'entità intersecata ordinaria verrà creata per supportare la relazione. Poiché è consigliabile utilizzare le proprietà di navigazione per eseguire operazioni che includono relazioni molti-a-molti, le entità intersecate ordinarie non sono documentate ma sono ancora disponibili mediante l'API Web. Questi tipi di entità intersecate sono accessibili tramite un nome set di entità che utilizza la convenzione di denominazione seguente: <nome logico entità intersecata>+ 'raccolta'. Ad esempio, puoi recuperare le informazioni dal tipo di entità intersecata contactleads mediante [URI organizzazione]/api/data/v8.2/contactleadscollection. È consigliabile utilizzare solo queste entità intersecate ordinarie nelle situazioni in cui desideri applicare la traccia delle modifiche.

Azioni

Le azioni sono operazioni che producono effetti collaterali, ad esempio la modifica dei dati, e che non possono essere ulteriormente composte per evitare il comportamento non deterministico

Nell'argomento Web API Action Reference vengono elencate tutte le azioni di sistema disponibili.Ulteriori informazioni:Utilizzare le azioni API Web.

Funzioni

Le funzioni sono operazioni che non dispongono di effetti collaterali e possono supportare composizione aggiuntiva, ad esempio, con altre operazioni di filtro, funzionalità o azione

Esistono due tipi di funzioni definite nell'API Web:

• Nell'argomento Web API Function Reference vengono elencate ogni funzione di sistema disponibile.

• Nell'argomento Web API Query Function Reference vengono elencate le funzioni intese per essere utilizzate come criteri in una query.

Ulteriori informazioni:Utilizzare le funzioni API Web

Tipi complessi

I tipi complessi sono tipi strutturati denominati keyless che sono costituiti da un set di proprietà. I tipi complessi sono comunemente utilizzati come valori di proprietà nelle entità di modello o sotto forma di parametri o valori restituiti per le operazioni.

Nell'argomento Web API ComplexType Reference sono elencati tutti i tipi di sistema complessi. I tipi complessi sono tipi strutturati denominati keyless che sono costituiti da un set di proprietà. Sono comunemente utilizzati come valori di proprietà nelle entità di modello o sotto forma di parametri o valori restituiti per le operazioni. Di seguito viene fornito il WhoAmIResponse ComplexType da CSDL.

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

Tipi di enumerazione

I tipi di enumerazione o EnumTypes sono tipi di primitivi denominati i cui valori sono denominati costanti con i valori interi sottostanti.

Nell'argomento Web API EnumType Reference sono elencati tutti i tipi di enumerazione di sistema. I tipi di enumerazione sono tipi di primitivi denominati i cui valori sono denominati costanti con i valori interi sottostanti. Di seguito viene fornito il AccessRights EnumType da CSDL.

<EnumType Name="AccessRights">
  <Member Name="None" Value="0" />
  <Member Name="ReadAccess" Value="1" />
  <Member Name="WriteAccess" Value="2" />
  <Member Name="AppendAccess" Value="4" />
  <Member Name="AppendToAccess" Value="16" />
  <Member Name="CreateAccess" Value="32" />
  <Member Name="DeleteAccess" Value="65536" />
  <Member Name="ShareAccess" Value="262144" />
  <Member Name="AssignAccess" Value="524288" />
</EnumType>

Vedere anche

Utilizzare l'API Web di Microsoft Dynamics 365
Autenticazione a Microsoft Dynamics 365 con l'API Web
Eseguire operazioni tramite l'API Web

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright