Redacció de sol·licituds HTTP i gestió d'errors per a l'API web del portals

La interacció amb l'API web inclou la composició de sol·licituds HTTP amb les capçaleres necessàries i la gestió de respostes HTTP, incloent-hi els errors.

Important

  • La versió del portal ha de ser 9.3.3.x o posterior per poder treballar amb aquesta característica.

URL i versions de l'API web

La construcció de l'adreça URL de l'API web mitjançant el format a la taula següent.

Part Descripció
Protocol https://
Adreça URL base <portal URL>
Camí de l'API web _api
Recurs Nom de la taula que voleu utilitzar

Per exemple, utilitzeu aquest format en fer referència a un cas:

https://contoso.powerappsportals.com/_api/case

Tots els recursos de l'API web seguiran els permisos de la taula del portal respectius en context amb les funcions web.

Mètodes HTTP

Les sol·licituds HTTP poden utilitzar mètodes de diversos tipus. No obstant això, l'API web dels portals només admet els mètodes de la taula següent:

Mètode Ús
Obtén el Yammer S'utilitza en recuperar dades de taules.
Post Utilitzeu-lo en crear taules i cridar accions.
Patch Utilitzeu-ho quan actualitzeu taules o feu operacions upsert.
Delete Utilitzeu-ho per suprimir taules o propietats individuals de les taules.
Put Utilitzeu-ho en situacions limitades per actualitzar les propietats individuals de taules.

Capçaleres HTTP

L'API web només admet JSON. Cada capçalera HTTP ha d'incloure:

  • Un valor de capçalera per a Accept application/json, encara que no s'esperi cap cos de resposta.
  • Si la sol·licitud inclou dades JSON al cos de la sol·licitud, heu d'incloure una capçalera Content-Type amb un valorapplication/json.

La versió actual d'OData és la 4.0, però les futures versions podrien permetre noves capacitats. Utilitzeu la sintaxi següent per assegurar-vos que no hi ha ambigüitat sobre la versió OData que s'aplicarà al vostre codi en el futur:

Sintaxi

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Exemple: funció Wrapper AJAX per al testimoni 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)

Exemple: recupera les dades de la taula

    webapi.safeAjax({
                type: "GET",
                url: "/_api/contacts?$select=firstname,lastname",
                contentType: "application/json",
                success: function (res) {
                        console.log(res);
                }
    });

Exemple: crear dades de taula

    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"))
        }
    });

Exemple: actualitzar dades de taula

        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);
        }
    });

Exemple: suprimir dades de taula

        webapi.safeAjax({
        type: "DELETE",
        url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
        contentType: "application/json",
        success: function (res) {
            console.log(res);
        }
    });

Identificar els codis d'estat

Cada sol·licitud HTTP a la resposta inclou un codi d'estat. Els codis d'estat retornats per l'API web dels portals inclouen el següent:

Codi Descripció Type
200 OK Espereu aquesta resposta si l'operació retornarà dades al cos de resposta. Correctes
204 No Content Espereu aquesta resposta si l'operació és correcta però no retornarà dades al cos de resposta. Correctes
403 Prohibit Espereu aquesta resposta per als tipus d'errors següents:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
Error del client
401 No autoritzat Espereu aquesta resposta per als tipus d'errors següents:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
Error del client
413 Payload Too Large Espereu aquesta resposta quan la longitud de la sol·licitud és massa gran. Error del client
400 BadRequest Espereu aquesta resposta quan un argument no és vàlid.
InvalidAttribute
Error del client
404 Not Found Espereu aquesta resposta quan el recurs no existeixi.
La taula no està exposada a l'API web.
Error del client
405 Method Not Allowed Aquest error es produeix per a combinacions incorrectes de mètodes i recursos. Per exemple, no podeu utilitzar DELETE o PATCH en una col·lecció de taules. Aquest situació pot ocórrer per als tipus d'errors següents:
  • InvalidOperation
  • NotSupported
Error del client
501 Not Implemented Espereu aquesta resposta quan algunes operacions sol·licitades no estan implementades. Error del servidor
503 Servei no disponible Espereu aquesta resposta quan el servei de l'API web no estigui disponible. Error del servidor

Analitzar els errors de la resposta

Considerem el següent exemple de resposta HTTP que encara inclou l'error intern:

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

Codis d'error

Els codis d'error es mostren en format hexadecimal per a tots els escenaris gestionats. A la taula següent s'enumera cada codi d'error amb el seu nom i el seu missatge respectiu.

Codi d'error Nom de l'error Missatge d'error
900400FF NoAttributesForTableCreate No hi ha atributs per l’acció de creació de taula.
90040100 InvalidAttribute No s’ha trobat l’atribut {0} per a la taula {1}.
90040101 AttributePermissionIsMissing L’atribut {0} de la taula {1} no està habilitat per a l’API web.
90040102 TablePermissionWriteIsMissingDuringUpdate No teniu permís per actualitzar l'entitat {0}.
90040103 TablePermissionCreateIsMissing No teniu permís per crear l'entitat {0}.
90040104 TablePermissionDeleteIsMissing No teniu permís per suprimir l'entitat {0.
90040105 TablePermissionAppendIsMissngDuringAssociationChange No teniu permís per associar o dissociar la taula {0} amb {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange No teniu permís per associar o dissociar la taula {1} a {0}.
90040107 HttpAntiForgeryException El testimoni de la galeta antifalsificació i el testimoni del camp de formulari no coincideixen.
90040109 MissingPortalSessionCookie S'ha passat un testimoni de sessió no vàlid al mètode de llançament.
9004010C ResourceDoesNotExists No s'ha trobat el recurs per al segment "{0}".
9004010D CDSError S'ha produït un error de CDS.

La resposta dels errors no gestionats amb el codi d'estat HTTP 500 retornarà l'error: "S'ha produït un error inesperat mentre es processava la sol·licitud".

Consulteu també

Informació general sobre l’API web de portals
Els portals escriuen, actualitzen i suprimeixen operacions mitjançant l'API web
Portals llegeixen operacions utilitzant l'API web