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.

URL dell'API Web e controllo delle versioni

Costruisci l'URL dell'API Web utilizzando il formato nella tabella seguente.

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 del portale 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:

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:

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.

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

Vedi anche

Panoramica dell'API Web dei portali
Operazioni di scrittura, aggiornamento ed eliminazione dei portali con l'API Web
Operazioni di lettura dei portali utilizzando l'API Web