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

Artigo
03/16/2023

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

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	Método	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 anexo 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	Método	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

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)

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

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.

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.

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

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

Associar

O exemplo que se segue atribuirá um contacto existente como contacto primário de uma conta existente.

var record = {};
record[primarycontactid@odata.bind] = "/contacts(00000000-0000-0000-0000-000000000002)"; 

webapi.safeAjax({
  type: "PATCH",
  contentType: "application/json",
  url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
  data: JSON.stringify(record),
    success: function (data, textStatus, xhr) {
      console.log("Record updated");
    }
});

Próximo passo

Como: Utilizar a API Web de portais

Partilhar via

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

Pré-requisitos

Criar um registo numa tabela

Criar básico

Associar registos de tabelas ao criar

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

Atualizar e eliminar registos ao utilizar a API Web

Atualização básica

Atualizar um único valor de propriedade

Eliminar ou limpar um valor de campo

Eliminação básica

Associar e desassociar tabelas utilizando a API Web

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

Remover uma referência a uma tabela

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

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

Associar tabelas ao criar

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

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

Exemplos AJAX da API Web

Função Wrapper AJAX

Criar

Atualizar

Delete

Associar

Próximo passo

Consulte também

Comentários

Recursos adicionais

Partilhar via

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

Pré-requisitos

Criar um registo numa tabela

Criar básico

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

Associar registos de tabelas ao criar

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

Atualizar e eliminar registos ao utilizar a API Web

Atualização básica

Atualizar um único valor de propriedade

Eliminar ou limpar um valor de campo

Eliminação básica

Associar e desassociar tabelas utilizando a API Web

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

Remover uma referência a uma tabela

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

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

Associar tabelas ao criar

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

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

Exemplos AJAX da API Web

Função Wrapper AJAX

Criar

Atualizar

Delete

Associar

Próximo passo

Consulte também

Comentários

Recursos adicionais