Compartilhar via

Usar operações de gravação, atualização e exclusão da API Web de portais

  • Artigo

Observação

Desde o dia 12 de outubro de 2022, os portais do Power Apps passaram a ser Power Pages. Mais Informações: O Microsoft Power Pages já está disponível para todos (blog)
Em breve, migraremos e mesclaremos a documentação dos portais do Power Apps com a documentação do Power Pages.

É possível executar operações da API Web disponíveis em portais. As operações da API Web consistem em solicitações e respostas HTTP. Este artigo fornece exemplos de operações de gravação, atualização e exclusão, métodos, URI e JSON de amostra que podem ser usados nas solicitações HTTP.

Importante

  • Sua versão do portal deve ser 9.3.3.x ou posterior para que este recurso funcione.

Pré-requisitos

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

  • A API Web de portais acessa registros da tabela e segue as permissões da tabela fornecidas a usuários por meio das funções Web associadas. Certifique-se de configurar as permissões de tabela corretas. Mais informações: Criar funções Web

Criar um registro em uma tabela

Observação

Ao fazer referência a tabelas do Dataverse usando a API Web dos portais, você precisa usar EntitySetName, por exemplo, para acessar a tabela de conta, a sintaxe do código usará EntitySetName de contas.

Criar básico

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

JSON de amostra para criar registros de tabela relacionados em uma operação

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

  • Um contato é criado porque é definido como uma propriedade de objeto da propriedade de navegação de valor único primarycontactid.
  • Uma oportunidade é criada porque é definida como um objeto dentro de uma matriz definida com o valor de uma propriedade de navegação com valor de coleção opportunity_customer_accounts.
  • Uma tarefa é criada porque é definida como um objeto em uma matriz definida com 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 registros da tabela ao criar

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

JSON de exemplo para criar uma anotação por meio 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 anexo como uma cadeia de caracteres base64.

Atualizar e excluir registros usando a API da Web

Atualização básica

Operação Método URI Exemplo de JSON
Atualização básica PATCH [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 o valor de uma única propriedade

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

Excluir ou limpar o valor de um campo

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

Exclusão básica

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

Associar e desassociar tabelas usando a API Web

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

Operação Método URI Exemplo de JSON
Adicionar uma referência a uma propriedade de navegação com valor de coleção Postar [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 única propriedade de navegação de valor único

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

Operação Método URI
Remover uma referência a uma tabela para uma única 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 em uma propriedade de navegação com valor único

Operação Método URI Exemplo de JSON
Alterar a referência em uma propriedade de navegação com 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

É possível criar tabelas com relações usando a inserção profunda.

Associar tabelas na atualização usando uma propriedade de navegação de valor único

Você pode associar tabelas na atualização usando a mesma mensagem descrita em Atualização básica, anteriormente neste tópico, mas é necessário usar 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 usando a propriedade de navegação de valor único customerid_account.

Associar tabelas na atualização usando uma propriedade de navegação de valor único

Operação Método URI Exemplo de JSON
Associar tabelas na atualização usando 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

Esta exemplo mostra como criar, atualizar e excluir registros de tabela usando o Asynchronous JavaScript e XML (AJAX).

Função AJAX do 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)

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

Atualizar

  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óxima etapa

Tutorial: usar a API Web do portal

Confira também

Visão geral da API Web de portais
Portais leem operações usando a API Web

Observação

Você pode nos falar mais sobre suas preferências de idioma para documentação? Faça uma pesquisa rápida. (Observe que esta pesquisa está em inglês)

A pesquisa levará cerca de sete minutos. Nenhum dado pessoal é coletado (política de privacidade).