Criar UI para editar um registro

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:
  • Fazer uma solicitação para que a API de interface de usuário atualize um registro.
  • Descrever o que há de especial nos campos compostos.
  • Fazer uma solicitação para que a API de interface de usuário atualize um campo composto.

Usar o Workbench para chamar a API de interface de usuário

Vamos usar o Workbench para fazer uma chamada de API para atualizar o registro Contêineres universais.

O Workbench é um conjunto de ferramentas para interação com sua organização do Salesforce por meio da API. Uma vez que você pode fazer solicitações REST a partir de qualquer remetente de HTTP, há muitas outras ferramentas disponíveis para você usar (por exemplo, cURL ou Postman). No entanto, visto que o Workbench fornece uma estrutura amigável especificamente para APIs do Salesforce, é a maneira perfeita de começar antes de você estar pronto para escrever uma integração completa.

A primeira etapa é fazer login no Workbench.
  1. Faça login no Trailhead Playground. Em outra guia do navegador, acesse o Workbench.
  2. Em Ambiente, selecione Produção.
  3. Em Versão da API, selecione o número mais alto disponível.
  4. Certifique-se de marcar a opção Concordo com os termos de serviço.
  5. Clique em Login com o Salesforce.

Você chegou à página inicial do Workbench. Para este módulo, usamos apenas uma das muitas ferramentas do Workbench, o REST Explorer.

No menu superior, selecione utilitários | REST Explorer.

É possível fazer chamadas de API de interface de usuário a partir do REST Explorer do mesmo modo que você faria em qualquer outra interface HTTP.

Chamada do Workbench para o recurso /ui-api/object-info.

Para fazer uma chamada de API, insira o URI do recurso, selecione um método HTTP, adicione o corpo da solicitação conforme a necessidade e clique em Executar.

Agora, siga em frente e use o Workbench para fazer essa solicitação! Insira esta URI, selecione OBTER e clique em Executar.
/services/data/v50.0/ui-api/object-info

A resposta é uma lista com todos os objetos compatíveis com a API de interface de usuário e seu Trailhead Playground.

Nota

Nota

Caso receba uma mensagem de erro, verifique se sua URI inclui a versão da API que você vê no Workbench.

Editar um registro

No aplicativo Visualizador de registros, quando o usuário clica para criar um registro, a solicitação para /ui-api/record-ui/{recordIds} pede ambos os modos, exibição e edição. A resposta JSON inclui os layouts de ambos os modos, para que o aplicativo tenha informações suficientes para criar um formulário que permita que os usuários editem o registro quando quiserem.

let recordViewUrl = action.creds.instanceUrl + '/services/data/v50.0/ui-api/record-ui/' 
  + action.recordId + '?formFactor=' + action.context.formFactor + '&layoutTypes=Full&modes=View,Edit';

Para permitir que o usuário edite um registro, o aplicativo exibe um formulário com campos editáveis. Quando o usuário clica em Salvar, a saga recordUpdater.js faz uma solicitação de CORREÇÃO ao recurso /ui-api/records/{recordId} para fazer a atualização.

let recordDataUrl = action.creds.instanceUrl + '/services/data/v50.0/ui-api/records/' + action.recordId;

Vamos usar o Workbench para atualizar um registro e, depois, exibir a alteração no aplicativo Visualizador de registros e no Salesforce. Para começar, precisamos da ID do registro a ser atualizado.

No aplicativo Visualizador de registros, em Itens recentes, clique em Contêineres Universais. Copie a ID do registro a ser usada na solicitação de CORREÇÃO. É possível copiar a ID do campo na parte superior do aplicativo ou clicar em Mostrar JSON e em records para ver a ID do registro. Aqui está um exemplo de JSON parecido com o que você está vendo.
"records": {
    "0010V00002JoU6hQAF": {
      "apiName": "Account",
      "childRelationships": {},
      "eTag": "412642214dd7ef34eb3e2bae5e645dcc",
  1. No Workbench, clique em Utilitários REST Explorer.
  2. Insira estas configurações:
    • Método HTTP: CORREÇÃO
    • URI de recurso: /services/data/v50.0/ui-api/records/{recordId}

      Substitua {recordId} pela ID do registro de Contêineres universais.

    • Corpo da solicitação:
      {
          "fields" : {
              "Website": "www.example.com",
              "Rating" : "Hot"
          }
      }
  3. Clique em Executar.
  4. Retorne ao aplicativo Visualizador de registros e clique em Exibir registro para recarregar o registro Contêineres universais.

    Os campos Site da Web e Classificação foram atualizados. Também é possível visualizar a alteração em sua organização do Salesforce.

Editar um campo composto

Pode ser um pouco complicado atualizar os campos compostos. Um campo composto agrupa vários campos com tipos de dados primitivos, como números ou sequência de caracteres, para representar um tipo de dados complexo, como local ou endereço. O campo composto é feito de campos componentes.

Por exemplo, BillingAddress é um campo composto. Os campos componentes dele são BillingStreet, BillingCity, BillingState e BillingCountry. Os valores do campo composto e os valores dos campos componentes são mapeados para os mesmos dados subjacentes armazenados no Salesforce. Eles sempre têm valores iguais.

Os campos compostos são somente leitura. Para editar um campo composto, é preciso atualizar seus campos componentes.

Caso o campo seja composto, sua propriedade objectInfo.fields[fieldName].compound é true.
"BillingAddress" : {
  "apiName" : "BillingAddress",
  "calculated" : false,
  "compound" : true,
  "compoundComponentName" : null,
  "compoundFieldName" : null,
  ...
Caso o campo seja componente de um campo composto, sua propriedade objectInfo.fields[fieldName].compoundComponentName contém o nome do componente e sua propriedade objectInfo.fields[fieldName].compoundFieldName contém o nome do respectivo campo composto.
"BillingCity": {
  "apiName": "BillingCity",
  "calculated": false,
  "compound": false,
  "compoundComponentName": "City",
  "compoundFieldName": "BillingAddress",
  ...
Para atualizar um endereço, informe os campos componentes como entradas separadas. Por exemplo, BillingAddress é um campo composto, então ele é somente leitura. Para atualizá-lo, é preciso atualizar suas partes.
  1. No Workbench, clique em Utilitários REST Explorer.
  2. Insira estas configurações:
    • Método HTTP: CORREÇÃO
    • URI de recurso: /services/data/v50.0/ui-api/records/{recordId}

      Substitua {recordId} pela ID do registro de Contêineres universais.

    • Corpo da solicitação:
      {
        "fields" : {
          "BillingPostalCode": "98112",
            "BillingState": "WA",
            "BillingCity": "Seattle",
            "BillingStreet" : "123 Main Street",
            "BillingCountry" : "USA"
        }
      }
  3. Clique em Executar.
  4. Retorne ao aplicativo Visualizador de registros e clique em Exibir registro para recarregar o registro Contêineres universais.

Observe o registro atualizado no aplicativo Visualizador de registros.

No modo de exibição, é melhor renderizar um campo composto como campo único. Campo composto no modo de exibição.

No modo de edição, renderize os campos componentes para que o usuário possa alterá-los. Para ver o registro em modo de edição, clique em Editar.O campo componente no modo de edição mostra cada campo componente.

ETags

ETag é um cabeçalho de HTTP que identifica exclusivamente uma resposta. Seu aplicativo pode retornar um ETag ao Salesforce usando o cabeçalho de solicitação HTTP If-None-Match.

Se o JSON a ser retornado pelo Salesforce for idêntico ao seu, você receberá um HTTP 304, o que significa que nada mudou e seu aplicativo não precisa desserializar outra carga.

O uso de ETags reduz o tráfego na rede e o uso de dados, além de melhorar o desempenho do aplicativo. Ele é proveitoso para cargas de metadados de objeto e layout porque eles não mudam com frequência.

Toda resposta da API de interface de usuário tem uma propriedade eTag que contém um cabeçalho de HTTP ETag, que é um identificador opaco que corresponde ao recurso. É possível ver a propriedade eTag e seu identificador em uma resposta recolhida de /ui-api/record-ui/{recordIds}.
root:{} 5 items
eTag:19d49d8dfba088456235a7cacc38138a
layoutUserStates:{} 1 item
layouts:{} 1 item
objectInfos:{} 1 item
records:{} 1 item

Quando expandimos layouts, objectInfos e records na resposta JSON, podemos ver que cada uma dessas respostas aninhadas também contém uma propriedade eTag. Isso acontece porque a API de UI tem recursos que retornam cada uma dessas respostas aninhadas como respostas de nível superior. Em cargas agregadas como /ui-api/record-ui/{recordIds}, cada parte da carga tem um ETag.

Esses recursos retornam as respostas aninhadas como respostas de nível superior.
  • /ui-api/layout/{objectApiName}
  • /ui-api/object-info/{objectApiName}
  • /ui-api/records/{recordId}

Recursos