Patch Función

Se aplica a: Aplicaciones de lienzo Copilot Studio Desktop fluyen aplicaciones controladas por modelos Funciones de Dataverse de la CLI de Power Platform

Modifica o crea uno o varios registros de un origen de datos o combina registros fuera de un origen de datos.

Use la Patch función para modificar registros en situaciones complejas, como cuando se realizan actualizaciones que no requieren interacción del usuario ni formularios que abarcan varias pantallas.

Para actualizar registros en un origen de datos más fácilmente para cambios simples, use el control Edit form en su lugar. Cuando agrega un control Edit form, proporciona a los usuarios un formulario para rellenar y después guarda los cambios en un origen de datos. Para más información, consulte Descripción de los formularios de datos.

Vea este vídeo para aprender a usar la Patch función :

Overview

Use la Patch función para modificar uno o varios registros de un origen de datos. Actualiza los valores de campos específicos sin afectar a otras propiedades. Por ejemplo, esta fórmula cambia el número de teléfono de un cliente llamado Contoso:

Patch( Customers, LookUp( Customers, Name = "Contoso" ), { Phone: "1-212-555-1234" } )

Use Patch con la función Defaults para crear registros. Use este comportamiento para crear una sola pantalla tanto para crear como para editar registros. Por ejemplo, la siguiente fórmula crea un registro para un cliente llamado Contoso:

Patch( Customers, Defaults( Customers ), { Name: "Contoso" } )

Incluso si no está trabajando con un origen de datos, puede usar Patch para combinar dos o más registros. Por ejemplo, esta fórmula combina dos registros en uno que identifica tanto el número de teléfono como la ubicación de Contoso:

Patch( { Name: "Contoso", Phone: "1-212-555-1234" }, { Name: "Contoso", Location: "Midtown" } )

Description

Modificar o crear un registro en un origen de datos

Para usar esta función con un origen de datos, especifique el origen de datos y, a continuación, especifique un registro base:

• Para modificar un registro, el registro base debe provenir de una fuente de datos. Podrías obtener el registro base a través de la propiedad Items de una galería, colocarlo en una variable de contexto o obtenerlo por otro camino. Pero debes poder rastrear el registro base hasta la fuente de datos. Este requisito es importante porque el registro incluye información adicional que te ayuda a encontrarlo de nuevo para su modificación.
• Para crear un registro, use la función Defaults para crear un registro base con valores predeterminados.

A continuación, especifique uno o más registros de cambio, cada uno de los cuales contenga nuevos valores de propiedad que reemplacen los valores de propiedad en el registro base. Los registros de cambio se procesan en orden, desde el principio de la lista de argumentos hasta el final, donde los valores de propiedad últimos reemplazan a los primeros.

El valor devuelto de Patch es el registro que modificó o creó. Si creó un registro, el valor devuelto podría incluir propiedades que el origen de datos generó automáticamente. Sin embargo, el valor de retorno no proporciona un valor para los campos de una tabla relacionada.

Por ejemplo, usa Set(MyAccount, Patch(Accounts, First(Account), 'Account Name': "Example name")); y luego MyAccount.'Primary Contact'.'Full Name'. No puede proporcionar un nombre completo en este caso. En su lugar, para acceder a los campos de una tabla relacionada, use una búsqueda separada como:

LookUp(Accounts, Account = MyAccount.Account).'Primary Contact'.'Full Name'

Al actualizar un origen de datos, puede surgir uno o varios problemas. Use IfError e IsError con el valor devuelto de Patch para detectar y responder a errores, como se describe en Control de errores. También puede usar la función Errors para identificar y examinar los problemas, como se describe en el tema sobre el uso de los orígenes de datos.

Las funciones relacionadas incluyen Update para reemplazar un registro entero o Collect para crear un registro. Use la función UpdateIf para modificar propiedades específicas de varios registros según una condición.

Modificar o crear un conjunto de registros en un origen de datos

También puedes usarlo Patch para crear o modificar varios registros con una sola llamada.

En lugar de pasar un solo registro base, proporciona una tabla de registros base en el segundo argumento. Proporciona también los registros de cambios en una tabla, correspondientes uno por uno con los registros base. El número de registros en cada tabla de cambios debe ser el mismo que el número de registros en la tabla base.

Cuando se usa Patch de esta manera, el valor de retorno también es una tabla con cada registro correspondiente uno por uno con los registros base y de cambio.

Combinar registros fuera de un origen de datos

Especifique dos o más registros que desee combinar. La función procesa los registros en el orden desde el principio hasta el final de la lista de argumentos, con los valores de propiedad posteriores que prevalecen sobre los anteriores.

Patch devuelve el registro combinado y no modifica sus argumentos ni registros en ningún origen de datos.

Syntax

Modificar o crear un registro en un origen de datos

Patch( DataSource, BaseRecord, ChangeRecord1 [, ChangeRecord2, ... ])

• DataSource: requerido. El origen de datos que contiene el registro que desea modificar o que contendrá el registro que desea crear.
• Registro base : obligatorio. El registro para modificar o crear. Si el registro proviene de una fuente de datos, la función encuentra y modifica el registro. Si se utiliza el resultado de Defaults , la función crea un registro. El DataSource de la instrucción patch y el DataSource de la función Defaults deben coincidir para crear un nuevo registro.
• ChangeRecords – Obligatorio. Uno o más registros que contienen propiedades para modificar en BaseRecord. La función procesa registros cambiando en orden desde el principio hasta el final de la lista de argumentos, con valores de propiedad posteriores que anulan a los anteriores.

Modificar o crear un conjunto de registros en un origen de datos

Patch( DataSource, BaseRecordsTable, ChangeRecordTable1 [, ChangeRecordTable2, ... ] )

• DataSource: requerido. El origen de datos que contiene los registros que desea modificar o que contendrá los registros que desea crear.
• BaseRecordTable – Obligatorio. Una tabla de registros para modificar o crear. Si el registro proviene de una fuente de datos, la función encuentra y modifica el registro. Si se utiliza el resultado de Defaults , la función crea un registro. El DataSource de la instrucción patch y el DataSource de la función Defaults deben coincidir para crear un nuevo registro.
• ChangeRecordTables – Obligatorio. Una o varias tablas de registros que contienen propiedades para modificar de cada registro de BaseRecordTable. La función procesa registros cambiando en orden desde el principio hasta el final de la lista de argumentos, con valores de propiedad posteriores que anulan a los anteriores.

Merge records

Patch( Record1, Record2 [, ...] )

• Registros - Obligatorio. Al menos dos de los registros que desea combinar. La función procesa los registros en orden desde el principio hasta el final de la lista de argumentos, con los valores de propiedades posteriores que anulan a los anteriores.

Examples

Modificar o crear un registro (en un origen de datos)

En estos ejemplos, se modifica o se crea un registro en una fuente de datos llamada IceCream. La fuente de datos contiene los datos de esta tabla y genera automáticamente los valores en la columnaID:

Para crear una versión en memoria de esta fuente de datos y así probar estos ejemplos, evalúa esta fórmula:

ClearCollect( IceCream,
    { ID: 1, Flavor: "Chocolate", Quantity: 100 },
    { ID: 2, Flavor: "Vanilla", Quantity: 200 }
)

Tras evaluar las fórmulas anteriores, la fuente de datos termina con estos valores:

Combinar registros (fuera de un origen de datos)

Modificar o crear un conjunto de registros (en una fuente de datos)

Cuando usas Patch con tablas en lugar de registros individuales, puedes crear o modificar varios registros en una sola llamada. El valor de retorno es una tabla de registros que corresponde uno por uno con las tablas de entrada.

Este ejemplo actualiza la Cantidad para varios sabores en la fuente de datos de IceCream a la vez:

Patch(
    IceCream,
    Table(
        { ID: 1, Flavor: "Chocolate", Quantity: 150 },
        { ID: 2, Flavor: "Vanilla", Quantity: 200 }
    ),
    Table(
        { Quantity: 300 },
        { Quantity: 400 }
    )
)

El resultado es una tabla con los registros actualizados: { ID: 1, Flavor: "Chocolate", Quantity: 300 } y { ID: 2, Flavor: "Vanilla", Quantity: 400 }.

Este ejemplo crea múltiples registros nuevos usando los valores predeterminados:

Patch(
    IceCream,
    Table( Defaults( IceCream ), Defaults( IceCream ) ),
    Table(
        { Flavor: "Mint", Quantity: 60 },
        { Flavor: "Peach", Quantity: 80 }
    )
)

Para detectar errores cuando modificas varios registros, usa IfError. IfError es el mecanismo preferido y funciona entre los hosts Power Fx:

IfError(
    Patch(
        IceCream,
        baseRecords,
        changeRecords
    ),
    Notify( "Some records failed to update: " & FirstError.Message, NotificationType.Error )
)

Patch con tipos de columna Dataverse

Los siguientes ejemplos se aplican específicamente a fuentes de datos Microsoft Dataverse. Las formas de los registros varían según la fuente de datos (por ejemplo, SharePoint y SQL Server tienen formatos diferentes).

Columna de elección: Para establecer una columna de Elección, usa directamente el valor de enum. Este ejemplo establece una columna de elección de Estado en una tabla de Cuentas :

Patch(
    Accounts,
    LookUp( Accounts, 'Account Name' = "Contoso" ),
    { 'Status': 'Status (Accounts)'.Active }
)

Columna de búsqueda: Para establecer una columna de Búsqueda, proporciona un registro con la clave primaria de la tabla relacionada. Este ejemplo establece la consulta de Contacto Principal en un registro de Cuentas :

Patch(
    Accounts,
    LookUp( Accounts, 'Account Name' = "Contoso" ),
    { 'Primary Contact': LookUp( Contacts, 'Full Name' = "John Smith" ) }
)

Delegación en fórmulas que utilizan Patch

La Patch función en sí no está sujeta a delegación porque escribe en la fuente de datos en lugar de consultarla. Sin embargo, pueden aparecer advertencias de delegación en fórmulas que se usan Patch si la parte de selección de registros de la fórmula (como Filter, LookUp o ForAll) implica una consulta que supera los límites de delegación de fuentes de datos.

Cuando ves una advertencia de delegación en una fórmula que incluye Patch, comprueba si la advertencia se aplica a las funciones de recuperación de datos y no a Patch sí misma. Para más información sobre la delegación, consulta Entender la delegación en una aplicación canvas.

Errores comunes con la Patch función

Cuando usas la Patch función, pueden producirse errores debido a la conectividad de la fuente de datos, permisos o conflictos de datos. Utiliza IfError e IsError para detectar errores y responder adecuadamente.

• "Error de red al usar Patch función": Este error suele indicar que la app no puede acceder a la fuente de datos. Las causas comunes incluyen la pérdida de la conexión a internet, la fuente de datos temporalmente inaccesible o permisos insuficientes para el usuario actual. Envuelve la Patch llamada en IfError para proporcionar un mensaje significativo a los usuarios.

• "Existen conflictos con cambios en el servidor": Este error ocurre cuando otro usuario o proceso modifica el mismo registro entre el momento en que tu app lee el registro y escribe el cambio. Actualiza la fuente de datos llamando a la función Refresh y vuelve a intentar la operación.

• Errores de permiso: Si el usuario no tiene permiso para crear o modificar registros en la fuente de datos, la Patch llamada falla. Utiliza IfError para detectar errores relacionados con permisos y guiar al usuario.

Para patrones generales de manejo de errores, véase Manejo de errores.

Uso de As o ThisRecord

Utiliza la palabra clave As o ThisRecord en tu fórmula para evitar un contexto de evaluación ambiguo.

En el siguiente ejemplo, consideremos el primero Lookup de la If afirmación. (OrderID = A[@OrderID]) se espera que compare el OrderId en el Lookup ámbito con el OrderId de colección A en el ForAll alcance. En este caso, probablemente quieras A[@OrderId] resolver como un parámetro local. Pero es ambiguo.

Actualmente, Power Apps interpreta tanto el lado izquierdo OrderId como el derecho A[@OrderId] como un campo en el ámbito Lookup. Por lo tanto, Lookup siempre encuentra la primera fila en [dbo].[Orders1] porque la condición es siempre cierta (es decir, la de OrderId cualquier fila es igual a sí misma).

ClearCollect(
    A,
    Filter(
        '[dbo].[Orders1]',
        OrderId = 8888888
    )
);
ForAll(
    A,
    If(
        LookUp(
            '[dbo].[Orders1]',
            OrderId = A[@OrderId],
            "OK"
        ) = "OK",
        Patch(
            '[dbo].[Orders1]',
            LookUp(
                '[dbo].[Orders1]',
                OrderId = A[@OrderId]
            ),
            {
      OrderName: "val1"
       }
   ),
   Patch(
            '[dbo].[Orders1]',
            Defaults('[dbo].[Orders1]'),
            {
      OrderName: "val2"
       }
   )
    )
)

Uso de As o ThisRecord

Siempre que sea posible, utiliza el operador As o la palabra clave ThisRecord para desambiguar el lado izquierdo. Como se recomienda en el escenario anterior.

Cuando tu fórmula utiliza múltiples ámbitos con ForAll, Filter, y Lookup en la misma fuente de datos o tabla, los parámetros de alcance pueden chocar con el mismo campo en otro lugar. Por lo tanto, utiliza el operador As o ThisRecord para resolver el nombre del campo y evitar ambigüedades.

Por ejemplo, puedes usar el operador As para desambiguar en el siguiente ejemplo.

ClearCollect(
    A,
    Filter(
        '[dbo].[Orders1]',
        OrderId = 8888888
    )
);
ForAll(
    A,
    If(
        LookUp(
            '[dbo].[Orders1]' As B,
            B.OrderId = A[@OrderId],
            "OK"
        ) = "OK",
        Patch(
            '[dbo].[Orders1]',
            LookUp(
                '[dbo].[Orders1]' As C,
                C.OrderId = A[@OrderId]
            ),
            {
      OrderName: "val1"
       }
   ),
   Patch(
            '[dbo].[Orders1]',
            Defaults('[dbo].[Orders1]'),
            {
      OrderName: "val2"
       }
   )
    )
)

Alternativamente, puede usar ThisRecord con el mismo propósito.

ClearCollect(
    A,
    Filter(
        '[dbo].[Orders1]',
        OrderId = 8888888
    )
);
ForAll(
    A,
    If(
        LookUp(
            '[dbo].[Orders1]',
            ThisRecord.OrderId = A[@OrderId],
            "OK"
        ) = "OK",
        Patch(
            '[dbo].[Orders1]',
            LookUp(
                '[dbo].[Orders1]',
                ThisRecord.OrderId = A[@OrderId]
            ),
            {
      OrderName: "val1"
       }
   ),
   Patch(
            '[dbo].[Orders1]',
            Defaults('[dbo].[Orders1]'),
            {
      OrderName: "val2"
       }
   )
    )
)

Para saber más sobre el uso del operador As y de ThisRecord, consulte el artículo Operators .