Creare un'entità utilizzando l'API Web

Articolo
10/31/2017

Data di pubblicazione: gennaio 2017

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

Utilizza una richiesta POST per inviare i dati per creare un'entità. Puoi creare più entità correlate con un'unica operazione utilizzando l'inserimento deep. Devi inoltre essere in grado di impostare i valori per associare una nuova entità a quelle esistenti utilizzando l'annotazione @odata.bind.

Nota

Per informazioni su come creare e aggiornare i metadati dell'entità utilizzando l'API Web, vedi Creare e aggiornare definizioni di entità tramite la Web API.

In questo argomento

Creazione di base

Creare entità correlate con un'unica operazione

Associare le entità in fase di creazione

Creazione con dati restituiti

Creazione di base

In questo esempio viene creata una nuova entità account. L'intestazione OData-EntityId della risposta contiene l'URI dell'entità creata.

Richiesta

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

Risposta

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

Per creare una nuova entità, devi identificare i nomi e i tipi di proprietà validi. Per tutti gli attributi e le entità di sistema, puoi trovare queste informazioni nell'argomento relativo all'entità interessata nella Web API EntityType Reference. Per le entità o gli attributi personalizzati, fai riferimento alla definizione dell'entità interessata nel d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl.Ulteriori informazioni:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_entityTypes

Creare entità correlate con un'unica operazione

Puoi creare entità tra loro correlate definendole come valori di proprietà di navigazione. Questa operazione è nota con il nome di inserimento deep.

Con una creazione di base, l'intestazione OData-EntityId della risposta contiene l'Uri dell'entità creata. Gli URI delle entità correlate create non vengono restituiti.

Ad esempio, il seguente messaggio di richiesta pubblicato nel set di entità Account creerà un totale di quattro nuove entità nel contesto di creazione di un account.

Viene creato un contatto perché è definito come proprietà oggetto della proprietà di navigazione a valore singolo primarycontactid.
Viene creata un'opportunità perché è definita come un oggetto all'interno di un array che è impostato sul valore di una proprietà di navigazione con valori della raccolta opportunity_customer_accounts.
Viene creata un'attività perché è definita come un oggetto all'interno di un array che è impostato sul valore di una proprietà di navigazione con i valori della raccolta Opportunity_Tasks.

Richiesta

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
 "name": "Sample Account",
 "primarycontactid":
 {
     "firstname": "John",
     "lastname": "Smith"
 },
 "opportunity_customer_accounts":
 [
  {
      "name": "Opportunity associated to Sample Account",
      "Opportunity_Tasks":
      [
       { "subject": "Task associated to opportunity" }
      ]
  }
 ]
}

Risposta

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

Associare le entità in fase di creazione

Per associare le nuove entità con quelle esistenti quando vengono create, devi impostare il valore delle proprietà di navigazione a valore singolo utilizzando l'annotazione @odata.bind.

Il seguente messaggio di richiesta pubblicato nel set di entità account creerà un nuovo account associato a un contatto esistente con il valore di contactid pari a 00000000-0000-0000-0000-000000000001.

Richiesta

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
"name":"Sample Account",
"primarycontactid@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"
}

Risposta

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000002)

Nota

L'associazione di entità con questa modalità utilizzando una proprietà di navigazione con valori della raccolta non è supportata dall'API Web.

Creazione con dati restituiti

Nota

Questa funzionalità è stata aggiunta con Aggiornamento di dicembre 2016 per Dynamics 365 (online e locale).

Puoi creare la richiesta POST in modo che i dati del record creato vengano restituiti con lo stato 201 (Created). Per ottenere questo risultato, devi usare la preferenza return=representation nelle intestazioni della richiesta.

Per controllare quali proprietà vengono restituite, aggiungi l'opzione di query $select all'URL del set di entità. L'opzione di query $expand verrà ignorata se utilizzata.

Quando un'entità viene creata in questo modo, l'intestazione OData-EntityId contenente l'URI del record creato non viene restituita.

In questo esempio crei una nuova entità account che restituisce i dati richiesti nella risposta.

Richiesta

POST cc_WebAPI_ServiceURI/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

Risposta

HTTP/1.1 201 Created
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts/$entity",
    "@odata.etag": "W/\"536530\"",
    "accountid": "d6f193fc-ce85-e611-80d8-00155d2a68de",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Sample Account",
    "createdon": "2016-09-28T22:57:53Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

Vedere anche

Esempio di operazioni di base dell'API Web (C#)
Esempio di operazioni di base 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
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 funzioni 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

Condividi tramite

Creare un'entità utilizzando l'API Web

In questo argomento

Creazione di base

Creare entità correlate con un'unica operazione

Associare le entità in fase di creazione

Creazione con dati restituiti

Vedere anche

Risorse aggiuntive