Comporre richieste HTTP e gestire gli errori per l'API Web dei portali
L'interazione con l'API Web include la composizione delle richieste HTTP con le intestazioni richieste e la gestione delle risposte HTTP, inclusi eventuali errori.
Importante
- La versione del portale deve essere 9.3.3.x o successiva affinché questa funzionalità sia operativa.
URL dell'API Web e controllo delle versioni
Costruisci l'URL dell'API Web utilizzando il formato nella tabella seguente.
| In parte | Description |
|---|---|
| Protocollo | https:// |
| URL di base | <URL portale> |
| Percorso API Web | _api |
| Risorsa | Nome logico della tabella che desideri utilizzare |
Ad esempio, utilizza questo formato quando fai riferimento a un caso:
https://contoso.powerappsportals.com/_api/case
Tutte le risorse dell'API Web seguiranno le rispettive autorizzazioni tabella nel contesto dei ruoli Web.
Metodi HTTP
Le richieste HTTP possono utilizzare diversi tipi di metodi. Tuttavia, l'API Web dei portali supporta solo i metodi nella tabella seguente:
| metodo | Utilizzo |
|---|---|
| Get | Da utilizzare quando si recuperano dati dalle tabelle. |
| Registra | Usa per la creazione record. |
| Patch | Da utilizzare quando si aggiornano le tabelle o si eseguono operazioni di upsert. |
| Elimina | Utilizza quando elimini record o singoli valori di campo di record. |
| Put | Utilizza in situazioni limitate per aggiornare singoli campi di record. |
Intestazioni HTTP
L'API Web supporta solo JSON. Ogni intestazione HTTP deve includere:
- Un valore di intestazione Accetta di application/json, anche quando non è previsto alcun corpo della risposta.
- Se la richiesta include dati JSON nel corpo della richiesta devi includere un'intestazione Content-Type con un valore di
application/json.
La versione corrente di OData è 4.0, ma le versioni future possono permettere nuove funzionalità. Usa la seguente sintassi per assicurarti che non ci siano ambiguità sulla versione OData che verrà applicata al tuo codice in futuro:
Sintassi
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Esempio: funzione Wrapper AJAX per il token CSRF
(function(webapi, $){
function safeAjax(ajaxOptions) {
var deferredAjax = $.Deferred();
shell.getTokenDeferred().done(function (token) {
// add headers for ajax
if (!ajaxOptions.headers) {
$.extend(ajaxOptions, {
headers: {
"__RequestVerificationToken": token
}
});
} else {
ajaxOptions.headers["__RequestVerificationToken"] = token;
}
$.ajax(ajaxOptions)
.done(function(data, textStatus, jqXHR) {
validateLoginSession(data, textStatus, jqXHR, deferredAjax.resolve);
}).fail(deferredAjax.reject); //ajax
}).fail(function () {
deferredAjax.rejectWith(this, arguments); // on token failure, pass the token ajax and args
});
return deferredAjax.promise();
}
webapi.safeAjax = safeAjax;
})(window.webapi = window.webapi || {}, jQuery)
Esempio: recuperare i dati della tabella
webapi.safeAjax({
type: "GET",
url: "/_api/contacts?$select=firstname,lastname",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
Esempio: creare dati di tabella
webapi.safeAjax({
type: "POST",
url: "/_api/accounts",
contentType: "application/json",
data: JSON.stringify({
"name": "Sample Account"
}),
success: function (res, status, xhr) {
console.log("entityID: "+ xhr.getResponseHeader("entityid"))
}
});
Esempio: aggiornare dati di tabella
webapi.safeAjax({
type: "PATCH",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
contentType: "application/json",
data: JSON.stringify({
"name": "Sample Account - Updated"
}),
success: function (res) {
console.log(res);
}
});
Esempio: eliminare dati di tabella
webapi.safeAjax({
type: "DELETE",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
Individuare i codici di stato
Ogni risposta alla richiesta HTTP include un codice di stato. I codici di stato restituiti dall'API Web dei portali includono i seguenti:
| Codice | Description | Type |
|---|---|---|
| 200 OK | Quando l'operazione restituisce dati nel corpo della risposta, si riceve questa risposta. | Operazione riuscita |
| 204 No Content | Quando l'operazione ha esito negativo ma non restituisce dati nel corpo della risposta, si riceve questa risposta. | Operazione riuscita |
| 403 Negato | Per i seguenti tipi di errori, si riceve questa risposta:
|
Errore client |
| 401 Non autorizzato | Per i seguenti tipi di errori, si riceve questa risposta:
|
Errore client |
| 413 Payload Too Large | Quando la lunghezza richiesta è troppo grande, si riceve questa risposta. | Errore client |
| 400 BadRequest | Quando un argomento non è valido, si riceve questa risposta. InvalidAttribute |
Errore client |
| 404 Not Found | Quando la risorsa non esiste, si riceve questa risposta. La tabella non è esposta per l'API Web. |
Errore client |
| 405 Method Not Allowed | Questo errore si verifica in caso di combinazioni errate di metodo e risorsa. Ad esempio, non puoi utilizzare DELETE o PATCH in una raccolta di tabelle. Questa situazione si verifica per i seguenti tipi di errori:
|
Errore client |
| 501 Not Implemented | Quando un'operazione richiesta non viene implementata, si riceve questa risposta. | Errore server |
| 503 Servizio non disponibile | Quando il servizio API Web non è disponibile, si riceve questa risposta. | Errore server |
Analizzare gli errori dalla risposta
Considera la seguente risposta HTTP di esempio che include ancora l'errore interno:
{
"error":{
"code": "This code is not related to the http status code and is frequently empty",
"message": "A message describing the error",
"cdscode": "Dataverse error code",
"innererror": {
"code": "800xxxx",
"message": "A message describing the error. This is frequently the same as the outer message.."
}
}
}
Codici errore
I codici di errore vengono visualizzati in formato esadecimale per tutti gli scenari gestiti. La tabella seguente elenca ogni codice di errore con il rispettivo nome e messaggio.
| Codice errore | Nome errore | Messaggio di errore |
|---|---|---|
| 900400FF | NoAttributesForTableCreate | Nessun attributo per l'azione Crea tabella. |
| 90040100 | InvalidAttribute | Impossibile trovare l'attributo {0} per la tabella {1}. |
| 90040101 | AttributePermissionIsMissing | L'attributo {0} nella tabella {1} non è abilitato per l'API Web. |
| 90040102 | TablePermissionWriteIsMissingDuringUpdate | Non disponi dell'autorizzazione per aggiornare l'entità {0}. |
| 90040103 | TablePermissionCreateIsMissing | Non disponi dell'autorizzazione per creare l'entità {0}. |
| 90040104 | TablePermissionDeleteIsMissing | Non disponi dell'autorizzazione per eliminare l'entità {0). |
| 90040105 | TablePermissionAppendIsMissngDuringAssociationChange | Non disponi dell'autorizzazione per associare o disassociare la tabella {0} con {1}. |
| 90040106 | TablePermissionAppendToIsMissingDuringAssociationChange | Non disponi dell'autorizzazione per associare o disassociare la tabella {1} a {0} |
| 90040107 | HttpAntiForgeryException | Il token cookie anti-contraffazione e il token del campo modulo non corrispondono. |
| 90040109 | MissingPortalSessionCookie | Un token di sessione non valido è stato passato al metodo di lancio. |
| 9004010C | ResourceDoesNotExists | Risorsa non trovata per il segmento "{0}". |
| 9004010D | CDSError | Si è verificato un errore CDS. |
La risposta per errori non gestiti con il codice di stato HTTP 500 restituirà l'errore "Si è verificato un errore imprevisto durante l'elaborazione della richiesta".