Partilhar via

Utilizar as operações de escrita, atualização e eliminação da API Web de portais

  • Artigo

Nota

A partir de 12 de outubro de 2022, os portais do Power Apps passam a ser Power Pages. Mais informações: O Microsoft Power Pages está agora em disponibilidade geral (blogue)
Em breve, vamos migrar e unir a documentação dos portais do Power Apps com a documentação do Power Pages.

Pode executar operações de API Web disponíveis em portais. As operações API Web consistem em pedidos e respostas HTTP. Este artigo fornece operações de escrita, atualização e eliminação de amostra, métodos, URI e JSON de amostra que pode utilizar nos pedidos de HTTP.

Importante

  • A versão do seu portal tem ser a 9.3.3.x ou posterior para que esta funcionalidade funcione.

Pré-requisitos

  • Ative a tabela e o campo para as operações da API Web. Mais informações: Definições do site para a API Web

  • A API Web dos portais acede aos registos de tabelas e segue as permissões de tabela dadas aos utilizadores através das funções Web associadas. Certifique-se de que configura as permissões de tabela corretas. Mais informações: Criar funções Web

Criar um registo numa tabela

Nota

Quando se refere a tabelas do Dataverse que utilizam a API Web de portais, precisa de utilizar o EntitySetName, por exemplo, para aceder à tabela de conta, a sintaxe do código irá utilizar o EntitySetName de contas.

Criar básico

Operação Método URI Exemplo de JSON
Criar básico MENSAGEM [URI do Portal]/_api/accounts {"nome":"Conta de Exemplo"}

JSON de exemplo para criar registos de tabelas relacionados numa única operação

Como exemplo, o seguinte corpo do pedido publicado no conjunto de tabelas da Conta criará um total de quatro novas tabelas, incluindo a conta, no contexto da criação da conta.

  • É criado um contacto porque é definido como uma propriedade de objeto da propriedade de navegação de valor único primarycontactid.
  • É criada uma oportunidade porque é definida como um objeto numa matriz que é definida para o valor de uma propriedade de navegação com valor de coleção opportunity_customer_accounts.
  • É criada uma tarefa porque é definida como um objeto numa matriz que é definida para o valor de uma propriedade de navegação com valor de coleção Opportunity_Tasks.
{
 "name": "Sample Account",
 "primarycontactid":
 {
     "firstname": "Alton",
     "lastname": "Stott"
 },
 "opportunity_customer_accounts":
 [
  {
      "name": "Opportunity associated to Sample Account",
      "Opportunity_Tasks":
      [
       { "subject": "Task associated to opportunity" }
      ]
  }
 ]
}

Associar registos de tabelas ao criar

Operation Method URI Exemplo de JSON
Associar registos de tabelas ao criar POST [URI do Portal]/_api/accounts {"name":"Sample Account","primarycontactid@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"}

Amostra JSON para criar uma anotação através da API Web

{
    "new_attribute1": "test attribute 1",
    "new_attribute2": "test attribute 2",
    "new_comments": "test comments",
    "new_recordurl": recordURL,
    "new_feedback_Annotations":
        [
            {
                "notetext": "Screenshot attached",
                "subject": "Attachment",
                "filename": file.name,
                "mimetype": file.type,
                "documentbody": base64str,
            }
        ]
    }

documentbody conterá o acessório como uma cadeia base64.

Atualizar e eliminar registos ao utilizar a API Web

Atualização básica

Operação Método URI Exemplo de JSON
Atualização básica CORREÇÃO [URI do Portal]/_api/accounts(00000000-0000-0000-0000-000000000001) { "name": "Updated Sample Account ", "creditonhold": true, "address1_latitude": 47.639583, "description": "This is the updated description of the sample account", "revenue": 6000000, "accountcategorycode": 2 }

Atualizar um único valor de propriedade

Operação Método URI Exemplo de JSON
Atualizar um único valor de propriedade PUT [URI do Portal]/_api/accounts(00000000-0000-0000-0000-000000000001)/name {"value": "Updated Sample Account Name"}

Eliminar ou limpar um valor de campo

Operation Method URI
Eliminar ou limpar um valor de campo DELETE [URI do Portal]/_api/accounts(00000000-0000-0000-0000-000000000001)/description

Eliminação básica

Operação Método URI
Eliminação básica DELETE [URI do Portal]/_api/accounts(00000000-0000-0000-0000-000000000001)

Associar e desassociar tabelas utilizando a API Web

Adicionar uma referência a uma propriedade de navegação de valor de coleção

Operação Método URI Exemplo de JSON
Adicionar uma referência a uma propriedade de navegação de valor de coleção PUBLICAR [URI do Portal]/_api/accounts(00000000-0000-0000-0000-000000000002)/opportunity_customer_accounts/$ref {"@odata.id":"[Portal URI]/_api/opportunities(00000000-0000-0000-0000-000000000001)"}

Remover uma referência a uma tabela

Operação Método URI
Remover uma referência a uma tabela DELETE [URI do Portal]/_api/accounts(00000000-0000-0000-0000-000000000002)/opportunity_customer_accounts/$ref?$id=[URI do Portal]/_api/opportunities(00000000-0000-0000-0000-000000000001)

Remover uma referência a uma tabela para uma propriedade de navegação de valor único

Para uma propriedade de navegação de valor único, remova o parâmetro de cadeia de consulta $id.

Operação Método URI
Remover uma referência a uma tabela para uma propriedade de navegação de valor único DELETE [URI do Portal]/_api/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref

Alterar a referência numa propriedade de navegação de valor único

Operação Método URI Exemplo de JSON
Alterar a referência numa propriedade de navegação de valor único PUT [URI do Portal]/_api/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref {"@odata.id":"[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000002)"}

Associar tabelas ao criar

As novas tabelas podem ser criadas com relações utilizando a inserção profunda.

Associar tabelas ao atualizar utilizando uma propriedade de navegação de valor único

Pode associar tabelas ao atualizar utilizando a mesma mensagem descrita na Atualização básica, no início deste tópico, mas tem de utilizar a anotação @odata.bind para definir o valor de uma propriedade de navegação de valor único. O exemplo a seguir altera a conta associada a uma oportunidade utilizando a propriedade de navegação de valor único customerid_account.

Associar tabelas ao atualizar utilizando uma propriedade de navegação de valor único

Operação Método URI Exemplo de JSON
Associar tabelas ao atualizar utilizando uma propriedade de navegação de valor único PATCH [URI do Portal]/_api/opportunities(00000000-0000-0000-0000-000000000001) {"customerid_account@odata.bind":"[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000002)"}

Exemplos AJAX da API Web

Este exemplo demonstra como criar, atualizar e eliminar registos de tabelas utilizando JavaScript e XML (AJAX) Assíncronos.

Função Wrapper AJAX

    (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)

Criar

    webapi.safeAjax({
        type: "POST",
        url: "/_api/accounts",
        contentType: "application/json",
        data: JSON.stringify({
            "name": "Sample Account"
        }),
        success: function (res, status, xhr) {
      //print id of newly created table record
            console.log("entityID: "+ xhr.getResponseHeader("entityid"))
        }
    });

Update

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

Delete

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

Próximo passo

Tutorial: Utilizar a API Web de portais

Consulte também

Descrição geral de API Web de portais
Os portais leem operações através da API Web

Nota

Pode indicar-nos as suas preferências no que se refere ao idioma da documentação? Responda a um breve inquérito. (tenha em atenção que o inquérito está em inglês)

O inquérito irá demorar cerca de sete minutos. Não são recolhidos dados pessoais (declaração de privacidade).