Uso di OData per eseguire query sui dati

  • 15 minuti

OData è un protocollo per eseguire query sulle API RESTful. Questa lezione esplora alcuni modi per eseguire operazioni CRUD sui dati Microsoft Dataverse.

Creazione di una riga

Per creare righe, usare il metodo HTTP POST.

POST [Organization URI]/api/data/v9.2/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
}

Recupero di righe

Per recuperare le righe, usare il metodo HTTP GET.

L'esempio seguente recupera un account con ID 00000000-0000-0000-0000-000000000001:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)

Sono disponibili altri metodi per eseguire query sui dati usando la sintassi delle query OData standard. Per altre informazioni su questo processo, vedere l'argomento Recupero di una riga di tabella mediante l'API Web.

Aggiornamento delle righe

A seconda di ciò che si sta cercando di ottenere, è possibile scegliere uno dei due metodi disponibili per l'aggiornamento delle righe:

  • Se si sta eseguendo un aggiornamento di più valori di attributo, usare il metodo HTTP PATCH. I metodi PATCH forniscono la funzionalità di upsert se viene specificato un valore di ID nella richiesta. Questa funzionalità risulta utile in caso di sincronizzazione dei dati tra sistemi.

  • Se si sta aggiornando un singolo valore di attributo, usare il metodo HTTP PUT. Non è possibile usare questo metodo con le proprietà di spostamento, ad esempio le ricerche, perché richiede la rimozione di un riferimento.

L'esempio seguente aggiorna una riga della tabella account:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

Per recuperare i dati dalla tabella in fase di aggiornamento, è possibile usare l'intestazione della richiesta return=representation. Per controllare quali proprietà vengono restituite, è possibile aggiungere una query $select all'URL del metodo PATCH. Nell'esempio seguente è stata aggiunta l'intestazione e $select è stato modificato in modo da includere solo gli attributi name, creditonhold e address1.

Richiesta

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$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":"Updated Sample Account"}

Risposta

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

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",
    "@odata.etag": "W/"536537"",
    "accountid": "00000000-0000-0000-0000-000000000001",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Updated Sample Account",
    "createdon": "2023-09-28T23:14:00Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

Il codice seguente è una richiesta PUT di esempio in cui viene aggiornato il nome di un account per una determinata riga:

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"value": "Updated Sample Account Name"}

Eliminazione di righe

Per eliminare le righe, usare il metodo HTTP DELETE. L'operazione è semplice in quanto è sufficiente specificare l'URI della riga di tabella da eliminare, come illustrato nella richiesta seguente:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Altre operazioni

In Dataverse sono disponibili molte altre operazioni predefinite che è possibile attivare tramite richieste dell'API Web. Per un elenco completo delle funzionalità disponibili, vedere l'argomento relativo all'esecuzione di operazioni tramite l'API Web.