Metodo PUT (framework di ADO.NET Data Services)

Negli elenchi ed esempi seguenti vengono descritti i protocolli per l'utilizzo del metodo PUT in ADO.NET Data Services. Altri comportamenti richiesti da Hypertext Transfer Protocol, RFC 2616 sono descritti in Requisiti HTTP comuni (framework di ADO.NET Data Services) e PUT, POST e DELETE (framework di ADO.NET Data Services).

I protocolli seguenti si applicano alle richieste HTTP che utilizzano il metodo PUT.

• Tutte le richieste PUT che vanno a buon fine restituiscono il codice di risposta 204 Nessun contenuto.

• In una richiesta PUT su una risorsa ADO.NET Data Services il contenuto della richiesta viene unito allo stato corrente della risorsa. L'unione è eseguita confrontando ogni componente del corpo della richiesta con lo stato della risorsa nel server.

  • Se il corpo della richiesta contiene un componente che non è presente nella risorsa, la richiesta rappresenta una violazione dello schema e viene restituito il codice di risposta 422 Entità non elaborabile.

  • Quando un componente nel corpo della richiesta corrisponde a un componente nella risorsa, il processo di corrispondenza viene esteso agli elementi figlio dell'elemento nel corpo della richiesta.

• Una richiesta PUT eseguita per impostare il valore di una risorsa su Null quando il tipo di risorsa non ammette valori Null genera il codice di risposta 422 Entità non elaborabile.

• Una richiesta PUT eseguita per impostare il valore di una risorsa su un valore vuoto quando il tipo di risorsa non definisce stati vuoti genera il codice di risposta 422 Entità non elaborabile.

• Poiché il metodo PUT deve essere idempotente, non può essere utilizzato per inserire risorse in un set di risorse. In altre parole, il metodo PUT non può implementare una semantica di aggiunta o creazione simile a quella del metodo POST.

• Eventuali annotazioni di contenuto posticipate nel payload della richiesta vengono ignorate.

• Se l'URI della richiesta nell'intestazione HTTP non corrisponde all'URI associato nel payload della richiesta, l'URI della richiesta ha la precedenza. Il payload verrà elaborato come se includesse il valore dell'URI della richiesta.

• Se il corpo della richiesta PUT contiene le chiavi per la risorsa o le risorse utilizzate come parte della serializzazione di una risorsa, i valori di tali chiavi vengono ignorati. I valori delle chiavi della risorsa non potranno essere aggiornati.

Tipi che supportano il metodo PUT

Negli esempi riportati più avanti in questo documento vengono riepilogati i tipi di risorse che supportano il metodo PUT. Una richiesta PUT a un tipo di risorsa che supporta il metodo PUT può non riuscire se il principio richiedente non dispone di sufficienti diritti per la risorsa specificata. In questo caso la richiesta restituisce il codice di risposta 401 Non autorizzato o 403 Accesso negato, a seconda che l'indicazione di un principio alternativo per il servizio dati possa consentire o meno la riuscita della richiesta, come è illustrato in Hypertext Transfer Protocol, RFC 2616.

Negli esempi seguenti sono illustrati gli elementi finali di sintassi del percorso HTTP dell'URL che supportano o meno il metodo PUT. Ogni esempio contiene la descrizione di una richiesta PUT e i risultati previsti.

/<EntitySet>

Elemento finale di un URI di esempio

Nell'URI di esempio seguente viene illustrato un set di entità come elemento finale:

/Customers

Descrizione:

Il metodo PUT non è supportato per un set di entità come elemento finale. Viene restituito il codice di risposta 405 Metodo non consentito.

/<EntitySet>(keyPredicate)

Nell'URI di esempio seguente viene illustrato un keyPredicate come elemento finale:

/Customers('ALFKI') 

Descrizione:

• Supporta il metodo PUT.

• Aggiorna la singola istanza del tipo di risorsa fornita dal corpo della richiesta e identificata da keyPredicate

  • Gli aggiornamenti completi ai tipi associati non sono supportati.

  • Supporta l'associazione del lato di una relazione con cardinalità uno.

• Consente di associare la risorsa R1 identificata da keyPredicate alle risorse esistenti:

  • Se la risorsa R1 contiene solo l'URI di una risorsa R2 esistente come valore di una proprietà di navigazione o collegamento che identifica il lato di una relazione con cardinalità uno, R1 viene associato a R2.

  • Se la risorsa R1 contiene l'URI e il corpo della risorsa, si presuppone che l'URI rappresenti una risorsa R2 esistente già associata a R1. La risorsa R2 viene quindi aggiornata con i valori specificati nel corpo.

  • Se la risorsa R1 contiene solo il corpo ma non l'URI di una risorsa R2 correlata come valore di una proprietà di navigazione o collegamento, viene restituito il codice di risposta 400 Richiesta non valida.

• L'invio a questa risorsa di un payload uguale al valore letterale Null genera il codice di risposta 400 Richiesta non valida.

• Non è possibile aggiornare il valore della proprietà o delle proprietà che costituiscono la chiave della risorsa. I nuovi valori eventualmente presenti nel payload di una richiesta PUT vengono ignorati.

Nell'URI di esempio seguente viene illustrato un predicato chiave di tipo numerico come elemento finale. Il codice aggiorna il prodotto 123 e la categoria alla quale è associato, quindi riassocia la categoria associata.

/Products(123)

Formato JSON

{
__metadata:{ uri="/Products(123)", 
type="NorthwindModel.Product" },
Name:"New product name"
Category :   { __metadata: {uri:"/Category(2)" } }
}

/<NavigationProperty> o /<LinkProperty>

Negli URI di esempio seguenti vengono illustrate le proprietà di navigazione e collegamento come elementi finali:

/Customers('ALFKI')/Orders

/Customers('ALKFI')/Orders(1)

/Products(1)/Category: è consentito solo nelle relazioni che terminano con cardinalità = 1

Descrizione:

• Supporta il metodo PUT.

• Se la proprietà di navigazione o collegamento identifica una sola risorsa o la fine di una relazione con cardinalità = 1:

  • Utilizza la stessa semantica prevista per /<ResourceSet>(keyPredicate), con l'eccezione che in un corpo di richiesta che contiene solo il valore Null la risorsa viene dissociata dalla risorsa identificata dal penultimo segmento URI.

• Se la proprietà di navigazione o collegamento identifica più risorse o la fine "multipla" di una relazione:

  • Non supportato; viene restituito il codice di risposta 405 Metodo non consentito.

/<ComplexType>

Nell'URI di esempio seguente viene illustrato un tipo complesso come elemento finale:

/Customers('ALFKI')/Address

Descrizione:

• Supporta il metodo PUT.

• Aggiorna il tipo complesso identificato dall'elemento foglia dell'URI di richiesta con il contenuto del corpo della richiesta.

• Supporta aggiornamenti completi.

• Il payload della richiesta può contenere il contenuto aggiornabile di tipi complessi nidificati. Non è definito alcun limite di profondità per tali aggiornamenti purché la profondità rimanga all'interno dell'istanza del tipo di risorsa contenitore.

/<Property>

Nell'URI di esempio seguente viene illustrata una proprietà come elemento finale:

/Customers('ALFKI')/FirstName

Descrizione:

• Supporta il metodo PUT.

• Supporta l'aggiornamento del valore della proprietà.

• È possibile impostare la proprietà su Null.

  • JSON utilizza il tipo primitivo Null.

/<Property>/$value

Nell'URI di esempio seguente viene illustrato un valore di proprietà come elemento finale:

/Customers('ALFKI')/FirstName/$value

Descrizione:

• Supporta il metodo PUT.

• Supporta l'aggiornamento del valore non elaborato della proprietà.

• Non consente di impostare il valore su Null.

• Il tipo MIME del corpo della richiesta deve corrispondere a quello del tipo della risorsa presente nel server.

• Con un corpo di richiesta di zero byte la proprietà viene impostata su un valore vuoto se il tipo della proprietà definisce uno stato vuoto; altrimenti, viene restituito il codice di risposta 422 Entità non elaborabile.

/<ServiceOperationName>

Nell'URI di esempio seguente viene illustrato il nome di un'operazione di servizio come elemento finale:

/CustomersByCity?city='London'

Descrizione:

• Non supporta il metodo PUT.

• Il verbo PUT non viene definito per operazioni ADO.NET Data Services.

• Restituisce il codice di risposta 405 Metodo non consentito.

Limitazione di andata e ritorno su richieste PUT

Il framework di ADO.NET Data Services supporta uno scenario di andata e ritorno che utilizza una richiesta GET su un determinato URI per restituire un payload. Uno scenario tipico sarebbe quello di modificare alcuni dati e passare lo stesso payload in una richiesta PUT nell'URI specificato. L'operazione non funziona quando la proprietà di un'entità non è una chiave ma una colonna di identità. L'unica soluzione in questo caso consiste nel modificare la colonna di identità contenuta nel file SSDL (Store Schema Definition Language) in una proprietà calcolata.

Vedere anche

Concetti

HttpWebRequest GET (framework di ADO.NET Data Services)
HttpWebRequest PUT (framework di ADO.NET Data Services)
HttpWebRequest POST (framework di ADO.NET Data Services)
HttpWebRequest DELETE (framework di ADO.NET Data Services)
PUT, POST e DELETE (framework di ADO.NET Data Services)