Usar a função Patch para criar e editar registros

  • 8 minutos

A função Patch é usada para criar e editar registros em uma fonte de dados quando o uso de um controle de Formulário não atende às suas necessidades. Patch é usada com mais frequência quando você precisa agir de maneira repetitiva em relação aos dados sem interação do usuário. Você também a utiliza se o design do aplicativo não permite o uso de formulários.

Usar Patch para criar um registro

A função Patch pode ser usada para criar um novo registro na fonte de dados. Para criar um registro, há três partes na fórmula.

  1. Inclua o nome da fonte de dados que deseja editar. Pode ser uma fonte de dados tabular (como o Microsoft Dataverse ou o SharePoint) ou uma coleção. Por exemplo, você usará CustomerOrders como o nome da fonte de dados.

  2. A função Defaults retorna um registro que contém os valores padrão da fonte de dados. Se uma coluna na fonte de dados não tiver um valor padrão, essa propriedade não estará presente. O uso de Defaults com a fonte de dados notifica a função Patch para criar um novo registro.

  3. Inclua as colunas que você deseja preencher no novo registro. Aqui você especificará o nome da coluna a ser atualizado, seguido do valor a ser gravado nessa coluna. Neste exemplo, você atualizará as colunas Region e Country com um valor de cadeia de caracteres.

A fórmula de exemplo é a seguinte:

Patch(CustomerOrders, Defaults(CustomerOrders), {Region: "Americas", Country: "Canada"})

Essa fórmula criará um registro na fonte de dados CustomerOrders e definirá Region como Americas e Country como Canada. Observe que você não define informações de chave primária (a coluna ID) que a fonte de dados atualiza de acordo com suas configurações.

Usar Patch para editar um registro

Também é possível editar um registro na fonte de dados. Para editar um único registro, há três partes na fórmula.

  1. Inclua o nome da fonte de dados que deseja editar. Pode ser uma fonte de dados tabular (como o Dataverse ou o SharePoint) ou uma coleção. Por exemplo, você usará CustomerOrders como o nome da fonte de dados.

  2. O registro que você deseja editar na fonte de dados. A maneira mais comum de especificar esse registro é usar a função LookUp para recuperar o registro da fonte de dados. Outra opção se você usa uma Galeria e quer atualizar o registro atual é usar a função ThisItem para fazer referência ao registro. Para este exemplo, você usará uma função LookUp.

  3. Inclua as alterações que deseja fazer. Aqui você especificará o nome da coluna a ser atualizado, seguido do valor a ser gravado nessa coluna. Neste exemplo, você atualizará as colunas Region e Country com um valor de cadeia de caracteres.

A fórmula de exemplo é a seguinte:

Patch(CustomerOrders, LookUP(CustomerOrders, ID = 1), {Region: "Asia", Country: "China"})

Essa fórmula atualizará o registro com uma ID igual a 1 na tabela CustomerOrders pela definição da coluna Region como Asia e a coluna Country como China. Se houver valores existentes nesses campos, eles serão substituídos.

Atualizar colunas com Patch

A lógica principal da maioria das funções Patch é atualizar as colunas apropriadas com as informações corretas. Essa será a origem da maior parte da solução de problemas da função Patch. Use os pontos a seguir para ajudá-lo a trabalhar com a função Patch.

  • Verifique se você está atualizando todas as colunas necessárias da fonte de dados.

  • Você pode atualizar várias ou algumas das colunas opcionais, como preferir.

  • Verifique se os nomes das colunas estão escritos e com as iniciais maiúsculas corretas. Os nomes de colunas diferenciam maiúsculas de minúsculas.

  • Verifique se você está escrevendo o tipo de dados correto. Por exemplo, se a coluna na fonte de dados for um tipo numérico, você não poderá escrever um valor de cadeia de caracteres nela, mesmo se essa cadeia de caracteres contiver um número.

Existem quatro fontes para passar valores na fórmula a fim de usar Patch na fonte de dados:

  • Você pode embutir um valor em código. Um exemplo é se você deseja aplicar patch no status do registro com "Pendente". Nesse caso, a fórmula de Patch é semelhante a:

    Patch(CustomerOrders, Default(CustomerOrders), {Status: "Pending"})

    Essa fórmula cria um registro e define a coluna Status com o valor de cadeia de caracteres "Pendente."

  • Você pode referenciar uma variável. Por exemplo, você pode armazenar a cadeia de caracteres "Em Revisão" em uma variável chamada varStatus com a fórmula a seguir.

    Set(varStatus, "Under Review")

    A fórmula de Patch será:

    Patch(CustomerOrders, Default(CustomerOrders), {Status: varStatus})

    Essa fórmula cria um registro e define a coluna Status com o valor de cadeia de caracteres "Em Revisão."

  • Você pode referenciar o valor da propriedade de um controle. Um exemplo é definir o valor de um menu suspenso chamado Dropdown1 que continha as regiões. A fórmula de Patch será semelhante a esta:

    Patch(CustomerOrders, Default(CustomerOrders), {Status: Dropdown1.Selected.Value})

    Essa fórmula cria um registro e define a coluna Status com o valor do item selecionado no menu suspenso.

  • Você pode usar a saída de uma fórmula. Um exemplo seria definir o valor da coluna Owner usando FullName da função User(). A fórmula de Patch será semelhante a esta:

    Patch(CustomerOrders, Default(CustomerOrders), {Owner: User().FullName})

    Essa fórmula cria um novo registro e define a coluna Owner como o FullName do usuário atual do Microsoft Entra ID.

Exemplo de Patch

Vamos conferir outro exemplo. Nesse exemplo, você está tentando criar uma solução para inscrever usuários na classe assim que eles chegam. Esse tipo de solução do Power Apps é comum, e a função Patch ajuda a obter resultados rapidamente.

Captura de tela de um exemplo de patch de solução do Power Apps.

Detalhamento da solução

Aqui vemos um aplicativo de Tela simples conectado à fonte de dados (TrainingClassSignIn). A fonte de dados tem as seguintes colunas: Training Class, FirstName, LastName, EmailAddress, SignInStatus. Essas são as informações que desejamos capturar quando um usuário seleciona o botão Sign In. Na barra de fórmulas, você vê o seguinte código:

Patch(TrainingClassSignIn,Defaults(TrainingClassSignIn),{TrainingClass:TrainingClassDD.Selected.Value, FirstName:FirstNameInput.Text, LastName:LastNameInput.Text, EmailAddress:EmailAddressInput.Text, SignInStatus:"Attended"})

Para elaborar, sempre que alguém seleciona o botão Sign In, o Power Apps grava um novo registro na fonte de dados TrainingClassSignIn. Quanto aos dados que são gravados para o usuário que entra, você pode ver que ele está obtendo essas informações dos diferentes controles que adicionamos (codificados por cores na fórmula). Você também pode notar que o código define SignInStatus sempre como "Assistido" para cada novo registro enviado.

Como você pode ver, a função Patch é flexível e avançada. Patch tem ainda mais funcionalidades, inclusive a capacidade de atualizar vários registros e mesclar registros. Para obter mais informações sobre esses cenários, confira Função Patch no Power Apps.