Tutorial: Utilitzar l'API web del portal

Article
09/20/2024

En aquesta guia, configurareu una pàgina web i una plantilla web personalitzada que utilitzarà l'API web per llegir, escriure, actualitzar i suprimir registres de la taula de contactes.

Nota

Podeu canviar els noms de les columnes o utilitzar una taula diferent seguint els passos d'aquest exemple.

Pas 1. Creeu la configuració de lloc

Per poder utilitzar l'API web de portals, heu d'habilitar la configuració del lloc necessari amb l'aplicació d'administració del portal. La configuració del lloc depèn de la taula que voleu utilitzar quan interactueu amb l'API web.

Inicieu l'aplicació d'administració de portals.
A la subfinestra esquerra de l'aplicació d'administració del portal, seleccioneu Configuració del lloc.
Seleccioneu Crea.
Al quadre de Nom, introduïu Webapi/contacte/habilitat.
A la llista de Llocs web, seleccioneu el registre del lloc web.
Al quadre Valor, introduïu cert.
Seleccioneu Desa i tanca.
Seleccioneu Crea.
Al quadre de Nom, introduïu Webapi/contacte/camps.
A la llista de Llocs web, seleccioneu el registre del lloc web.
Al quadre Valor, introduïu
nom,cognom,nom complet,adreça de correu electrònic1,telèfon1
Seleccioneu Desa i tanca.
Seleccioneu Crea.
Al quadre de Nom, introduïu Webapi/error/errorintern.
A la llista de Llocs web, seleccioneu el registre del lloc web.
Al quadre Valor, introduïu cert.
Seleccioneu Desa i tanca.
Verifiqueu la configuració del lloc de l'API web.

Pas 2. Configurar els permisos

Haureu de configurar els permisos per tal que els usuaris puguin utilitzar la característica de l'API web. En aquest exemple, heu de configurar o crear una nova funció web que utilitzarà l'API web, afegireu els permisos de taula per a la taula Contactes, associareu el permís de taula a la funció web i assignareu la funció web als usuaris per permetre'ls utilitzar l'API web.

Nota

L'API web segueix els permisos de taula que venen del context de la funció web de l'usuari autenticat o de la funció web anònima. Considereu si els usuaris ja tenen una funció web que té accés a les taules específiques del lloc web que necessita l'API web. No cal que creeu funcions web addicionals només per utilitzar l'API web.

Crear una funció web

Si actualment no teniu una funció web amb permisos a la taula a la qual esteu accedint a través de l'API web o necessiteu un context diferent per accedir a les dades, seguiu els passos següents per tal que us formeu com crear una funció web nova i assignar permisos de taula.

Inicieu l'aplicació d'administració de portals.
A la subfinestra esquerra, a Seguretat, seleccioneu Funcions web.
Seleccioneu Crea.
Al quadre Nom, introduïu Usuari de l'API web (o qualsevol nom que reflecteixi millor la funció de l'usuari que accedeix a aquesta funcionalitat).
A la llista de Llocs web, seleccioneu el registre del lloc web.
Seleccioneu Desa.

Crear permisos de taula

Obriu l'estudi de disseny de Power Pages.
Seleccioneu l'àrea de treball Seguretat .
A la secció Protegeix , seleccioneu Permisos de taula.
Seleccioneu Permís nou.
Al quadre Nom, introduïu Permís de taula de contacte.
A la llista Nom de la taula, seleccioneu Contacte (contacte).
A la llista Tipus d'accés, seleccioneu Global.
Seleccioneu els privilegis Lectura, Escriptura, Creació i Supressió.
Seleccioneu + Afegeix funcions i seleccioneu la funció web que seleccioneu o creeu abans.
Seleccioneu Desa i tanca.

Afegir contactes a la funció web

Inicieu l'aplicació d'administració de portals.
A la subfinestra esquerra, a Seguretat, seleccioneu Contactes.
Seleccioneu un contacte que vulgueu veure en aquest exemple per a l'API web.

Nota

Aquest contacte és el compte d'usuari que s'utilitza en aquest exemple per provar l'API web. Assegureu-vos de seleccionar el contacte correcte al portal.
Seleccioneu Relacionat>Funcions web.
Seleccioneu Afegeix una funció web existent.
Seleccioneu la funció d'Usuari de l'API web creada prèviament.
Seleccioneu Afegeix.
Seleccioneu Desa i tanca.

Pas 3. Creeu una pàgina web

Ara que heu habilitat l'API web i heu configurat els permisos d'usuari, creeu una pàgina web amb el codi d'exemple per visualitzar, editar, crear i suprimir registres.

Obriu l'estudi de disseny de Power Pages.
A l'àrea de treball Pàgines, seleccioneu + Pàgina.
Al quadre de diàleg Afegeix una pàgina;
Al quadre Nom, introduïu WebAPI i seleccioneu la disposició Comença des de zero.
Seleccioneu Afegeix.
Seleccioneu l'opció Edita el codi a la part superior dreta.
Seleccioneu Obre Visual Studio Code.

Copieu el fragment de codi de mostra següent i enganxeu-lo entre les etiquetes <div></div> de la secció de pàgina.

    <!-- Sample code for Web API demonstration -->
<style>
    #processingMsg {
        width: 150px;
        text-align: center;
        padding: 6px 10px;
        z-index: 9999;
        top: 0;
        left: 40%;
        position: fixed;
        -webkit-border-radius: 0 0 2px 2px;
        border-radius: 0 0 2px 2px;
        -webkit-box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
        box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
        display: none;
    }

    table td[data-attribute] .glyphicon-pencil {
        margin-left: 5px;
        opacity: 0;
    }

    table td[data-attribute]:hover .glyphicon-pencil {
        opacity: 0.7;
    }
</style>

<script>
  $(function() {
    //Web API ajax wrapper
    (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)
    // Notification component
    var notificationMsg = (function() {
      var $processingMsgEl = $('#processingMsg'),
        _msg = 'Processing...',
        _stack = 0,
        _endTimeout;
      return {
        show: function(msg) {
          $processingMsgEl.text(msg || _msg);
          if (_stack === 0) {
            clearTimeout(_endTimeout);
            $processingMsgEl.show();
          }
          _stack++;
        },
        hide: function() {
          _stack--;
          if (_stack <= 0) {
            _stack = 0;
            clearTimeout(_endTimeout);
            _endTimeout = setTimeout(function() {
              $processingMsgEl.hide();
            }, 500);
          }
        }
      }
    })();
    // Inline editable table component
    var webAPIExampleTable = (function() {
      var trTpl = '<% _.forEach(data, function(data){ %>' +
        '<tr data-id="<%=data.id%>" data-name="<%=data.fullname%>">' +
        '<% _.forEach(columns, function(col){ %>' +
        '<td data-attribute="<%=col.name%>" data-label="<%=col.label%>" data-value="<%=data[col.name]%>">' +
        '<%-data[col.name]%><i class="glyphicon glyphicon-pencil"></i>' +
        '</td>' +
        '<% }) %>' +
        '<td>' +
        '<button class="btn btn-default delete" type="submit"><i class="glyphicon glyphicon-trash" aria-hidden="true"></i></button>' +
        '</td>' +
        '</tr>' +
        '<% }) %>';
      var tableTpl = '<table class="table table-hover">' +
        '<thead>' +
        '<tr>' +
        '<% _.forEach(columns, function(col){ %>' +
        '<th><%=col.label%></th>' +
        '<% }) %>' +
        '<th>' +
        '<button class="btn btn-default add" type="submit">' +
        '<i class="glyphicon glyphicon-plus" aria-hidden="true"></i> Add Sample Record' +
        '</button>' +
        '</th>' +
        '</tr>' +
        '</thead>' +
        '<tbody>' + trTpl + '</tbody>' +
        '</table>';
      function getDataObject(rowEl) {
        var $rowEl = $(rowEl),
          attrObj = {
            id: $rowEl.attr('data-id'),
            name: $rowEl.attr('data-name')
          };
        $rowEl.find('td').each(function(i, el) {
          var $el = $(el),
            key = $el.attr('data-attribute');
          if (key) {
            attrObj[key] = $el.attr('data-value');
          }
        })
        return attrObj;
      }
      function bindRowEvents(tr, config) {
        var $row = $(tr),
          $deleteButton = $row.find('button.delete'),
          dataObj = getDataObject($row);
        $.each(config.columns, function(i, col) {
          var $el = $row.find('td[data-attribute="' + col.name + '"]');
          $el.on('click', $.proxy(col.handler, $el, col, dataObj));
        });
        //User can delete record using this button
        $deleteButton.on('click', $.proxy(config.deleteHandler, $row, dataObj));
      }
      function bindTableEvents($table, config) {
        $table.find('tbody tr').each(function(i, tr) {
          bindRowEvents(tr, config);
        });
        $table.find('thead button.add').on('click', $.proxy(config.addHandler, $table));
      }
      return function(config) {
        var me = this,
          columns = config.columns,
          addHandler = config.addHandler,
          deleteHandler = config.deleteHandler,
          $table;
        me.render = function(el) {
          $table = $(el).html(_.template(tableTpl)({
            columns: columns,
            data: me.data
          })).find('table');
          bindTableEvents($table, {
            columns: columns,
            addHandler: addHandler,
            deleteHandler: deleteHandler
          });
        }
        me.addRecord = function(record) {
          $table.find('tbody tr:first').before(_.template(trTpl)({
            columns: columns,
            data: [record]
          }));
          bindRowEvents($table.find('tbody tr:first'), config);
        }
        me.updateRecord = function(attributeName, newValue, record) {
          $table.find('tr[data-id="' + record.id + '"] td[data-attribute="' + attributeName + '"]').text(newValue);
        }
        me.removeRecord = function(record) {
          $table.find('tr[data-id="' + record.id + '"]').fadeTo("slow", 0.7, function() {
            $(this).remove();
          });
        }
      };
    })();
    //Applicaton ajax wrapper 
    function appAjax(processingMsg, ajaxOptions) {
      notificationMsg.show(processingMsg);
      return webapi.safeAjax(ajaxOptions)
        .fail(function(response) {
          if (response.responseJSON) {
            alert("Error: " + response.responseJSON.error.message)
          } else {
            alert("Error: Web API is not available... ")
          }
        }).always(notificationMsg.hide);
    }
    function loadRecords() {
      return appAjax('Loading...', {
        type: "GET",
        url: "/_api/contacts?$select=fullname,firstname,lastname,emailaddress1,telephone1",
        contentType: "application/json"
      });
    }
    function addSampleRecord() {
      //Sample data to create a record - change as appropriate
      var recordObj = {
        firstname: "Willie",
        lastname: "Huff" + _.random(100, 999),
        emailaddress1: "Willie.Huff@contoso.com",
        telephone1: "555-123-4567"
      };
      appAjax('Adding...', {
        type: "POST",
        url: "/_api/contacts",
        contentType: "application/json",
        data: JSON.stringify(recordObj),
        success: function(res, status, xhr) {
          recordObj.id = xhr.getResponseHeader("entityid");
          recordObj.fullname = recordObj.firstname + " " + recordObj.lastname;
          table.addRecord(recordObj);
        }
      });
      return false;
    }
    function deleteRecord(recordObj) {
      var response = confirm("Are you sure, you want to delete \"" + recordObj.name + "\" ?");
      if (response == true) {
        appAjax('Deleting...', {
          type: "DELETE",
          url: "/_api/contacts(" + recordObj.id + ")",
          contentType: "application/json",
          success: function(res) {
            table.removeRecord(recordObj);
          }
        });
      }
      return false;
    }
    function updateRecordAttribute(col, recordObj) {
      var attributeName = col.name,
        value = recordObj[attributeName],
        newValue = prompt("Please enter \"" + col.label + "\"", value);
      if (newValue != null && newValue !== value) {
        appAjax('Updating...', {
          type: "PUT",
          url: "/_api/contacts(" + recordObj.id + ")/" + attributeName,
          contentType: "application/json",
          data: JSON.stringify({
            "value": newValue
          }),
          success: function(res) {
            table.updateRecord(attributeName, newValue, recordObj);
          }
        });
      }
      return false;
    }
    var table = new webAPIExampleTable({
      columns: [{
        name: 'firstname',
        label: 'First Name',
        handler: updateRecordAttribute
      }, {
        name: 'lastname',
        label: 'Last Name',
        handler: updateRecordAttribute
      }, {
        name: 'emailaddress1',
        label: 'Email',
        handler: updateRecordAttribute
      }, {
        name: 'telephone1',
        label: 'Telephone',
        handler: updateRecordAttribute
      }],
      data: [],
      addHandler: addSampleRecord,
      deleteHandler: deleteRecord
    });
    loadRecords().done(function(data) {
      table.data = _.map(data.value, function(record){
        record.id = record.contactid;
        return record;
      });
      table.render($('#dataTable'));
    });
  });
</script>
<div id="processingMsg" class="alert alert-warning" role="alert"></div>
<div id="dataTable"></div>

Enganxar el codi.

Seleccioneu Ctrl+S per desar el codi.
A l'estudi de disseny, seleccioneu Sincronitza per actualitzar el lloc amb les edicions de codi.

Pas 4. Utilitzar l'API web per llegir, visualitzar, editar, crear i suprimir

Per provar la funcionalitat de l'API web:

Seleccioneu Visualització prèvia i, a continuació, trieu Escriptori.
Inicieu la sessió al lloc amb el compte d'usuari a qui s'hagi assignat la funció d'usuari de l'API web que heu creat abans.
Aneu a la pàgina web WebApi creada abans.
Seleccioneu Afegeix un registre d'exemple per afegir el registre d'exemple des de l'script.
Seleccioneu un camp. En aquest exemple, hem seleccionat correu electrònic per canviar l'adreça electrònica d'un contacte.
Seleccioneu la icona Suprimeix per eliminar un registre.

Ara que heu creat una pàgina web amb una mostra per llegir, visualitzar, editar, crear i suprimir registres, podeu personalitzar els formularis i la disposició.

Pas següent

Redactar sol·licituds HTTP i gestionar errors

Comparteix a través de