Patch funció

S'aplica a: Aplicacions de llenç Copilot Studio Fluxos d'escriptori Aplicacions basades en models Funcions del Power Platform CLI Dataverse

Modifica o crea un o diversos registres en una font de dades o combina els registres fora d'una font de dades.

Utilitzeu la Patch funció per modificar registres en situacions complexes, com ara quan feu actualitzacions que no requereixen interacció de l'usuari o utilitzeu formularis que abasten diverses pantalles.

Per actualitzar els registres d'una font de dades més fàcilment per a canvis senzills, utilitzeu el control Edita el formulari com a alternativa. Quan afegiu un control Edita el formulari, proporcioneu als usuaris un formulari que cal emplenar i, a continuació, desar els canvis en una font de dades. Per obtenir més informació, vegeu Entendre els formularis de dades.

Mireu aquest vídeo per aprendre a utilitzar la Patch funció:

Overview

Utilitzeu la Patch funció per modificar un o més registres d'una font de dades. Actualitza els valors de camps específics sense afectar altres propietats. Per exemple, aquesta fórmula canvia el número de telèfon d'un client anomenat Contoso:

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

Utilitzeu-lo Patch amb la funció Per defecte per crear registres. Utilitzeu aquest comportament per crear una única pantalla per crear i editar registres. Per exemple, aquesta fórmula crea un registre per a un client anomenat Contoso:

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

Note

Quan actualitzes una col·lecció utilitzant un registre d'una font de dades amb valors per defecte, l'operació actualitza la col·lecció tant amb els valors especificats com amb els valors per defecte de la font de dades. La DataSource de l'instrucció del patch i la funció DataSource de la funció Defaults han de coincidir per crear un nou registre.

Fins i tot si no treballeu amb una font de dades, podeu utilitzar-la Patch per combinar dos o més registres. Per exemple, aquesta fórmula combina dos registres en un que identifica el número de telèfon i la ubicació de Contoso:

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

Description

Modificar o crear un registre en una font de dades

Per utilitzar aquesta funció amb una font de dades, especifiqueu la font de dades i, a continuació, un registre base:

• Per modificar un registre, el registre base ha de provenir d'una font de dades. Pots obtenir el registre base a través de la propietat Elements d'una galeria, col·locar-lo en una variable de context o obtenir-lo per algun altre camí. Però has de poder rastrejar el registre base fins a la font de dades. Aquest requisit és important perquè el registre inclou informació addicional que t'ajuda a trobar-lo de nou per a la seva modificació.
• Per crear un registre, utilitzeu la funció Defaults per crear un registre base amb valors per defecte.

A continuació, especifiqueu un o diversos registres de canvi, cadascun dels quals conté els valors nous que substitueixen els valors de la propietat del registre base. Els registres de canvi es processen per ordre des de l'inici de la llista d'arguments fins al final, amb els valors de propietat més recents que sobreescriuen els anteriors.

El valor retornat de Patch és el registre que heu modificat o creat. Si heu creat un registre, el valor retornat pot incloure propietats que la font de dades va generar automàticament. No obstant això, el valor de retorn no proporciona cap valor per als camps d'una taula relacionada.

Per exemple, utilitzeu Set(MyAccount, Patch(Accounts, First(Account), 'Account Name': "Example name")); i, a continuació, MyAccount.'Primary Contact'.'Full Name'. En aquest cas, no es pot donar cap nom complet. Per accedir als camps d'una taula relacionada, utilitzeu una cerca independent, com ara:

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

Quan actualitzeu una font de dades, poden sorgir un o més problemes. Utilitzeu IfError i IsError amb el valor retornat de Patch per detectar i respondre als errors, tal com es descriu a la gestió d'errors . També podeu utilitzar la funció Errors per identificar i examinar els problemes, com es descriu a Treballar amb fonts de dades.

Entre les funcions relacionades hi ha la funció Update per substituir un registre sencer i la funció Collect per crear un registre. Utilitzeu la funció UpdateIf per modificar les propietats específiques de diversos registres en funció d'una condició.

Modificar o crear un conjunt de registres en una font de dades

També pots utilitzar Patch per crear o modificar múltiples registres amb una sola trucada.

En lloc de passar un registre base únic, proporciona una taula de registres base en el segon argument. Proporciona també registres de canvis en una taula, corresponent un per un amb els registres base. El nombre de registres de cada taula de canvi ha de ser el mateix que el nombre de registres de la taula base.

Quan s'utilitza Patch d'aquesta manera, el valor de retorn també és una taula amb cada registre corresponent un per un amb els registres base i de canvi.

Combinar registres fora d'una font de dades

Especifiqueu dos o més registres que voleu combinar. La funció processa els registres en l'ordre des de l'inici de la llista d'arguments fins al final, amb els valors de propietat posteriors que substitueixen els anteriors.

Patch Retorna el registre combinat i no modifica els seus arguments ni els registres de cap font de dades.

Syntax

Modificar o crear un registre en una font de dades

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

• DataSource : obligatori. La font de dades que conté el registre que voleu modificar o contindrà el registre que voleu crear.
• BaseRecord : obligatori. El registre que es modificarà o crearà. Si el registre prové d'una font de dades, la funció troba i modifica el registre. Si s'utilitza el resultat de Defaults , la funció crea un registre. El DataSource de la sentència patch i el DataSource de la funció Defaults han de coincidir per crear un registre nou.
• ChangeRecords : obligatori. Un o diversos registres que contenen propietats per modificar a BaseRecord. Els processos de la funció canvien els registres en ordre des de l'inici fins al final de la llista d'arguments, amb els valors de propietat posteriors que substitueixen els anteriors.

Modificar o crear un conjunt de registres en una font de dades

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

• DataSource : obligatori. La font de dades que conté els registres que voleu modificar o contindrà els registres que voleu crear.
• BaseRecordTable : obligatori. Una taula de registres que es modificarà o crearà. Si el registre prové d'una font de dades, la funció troba i modifica el registre. Si s'utilitza el resultat de Defaults , la funció crea un registre. El DataSource de la sentència patch i el DataSource de la funció Defaults han de coincidir per crear un registre nou.
• ChangeRecordTables : obligatori. Una o diverses taules de registres que contenen propietats que es modificaran per a cada registre de BaseRecordTable. Els processos de la funció canvien els registres en ordre des de l'inici fins al final de la llista d'arguments, amb els valors de propietat posteriors que substitueixen els anteriors.

Merge records

Patch( Registre1, Registre2 [, ...] )

• Registres : obligatori. Almenys dos registres que voleu combinar. La funció processa els registres en ordre des de l'inici fins al final de la llista d'arguments, amb els valors de propietat posteriors que substitueixen els anteriors.

Examples

Modificar o crear un registre (en una font de dades)

En aquests exemples, modifiques o crees un registre en una font de dades anomenada IceCream. La font de dades conté les dades d'aquesta taula i genera automàticament els valors a la columnaID:

Per crear una versió en memòria d'aquesta font de dades perquè puguis provar aquests exemples, avalua aquesta fórmula:

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

Formula	Description	Result
Patch( Gelat, LookUp( Gelat, Gust = "Xocolata" ), { Quantitat: 400 } )	Modifica un registre a la font de dades Gelat: La columna ID del registre que es modificarà conté el valor 1. (El registre Xocolata té aquest identificador). El valor de la columna Quantitat es canvia a 400.	{ ID:1, Gust: "Xocolata", Quantitat: 400 } L'entrada de Xocolata a la font de dades d'IceCream està modificada.
Patch( Gelat, Per defecte ( Gelat ), { Sabor: "Maduixa" } )	Crea un registre a la font de dades Gelat: La columna ID conté el valor 3, que la font de dades genera automàticament. La columna Quantitat conté 0, que és el valor per defecte de la columna a la font de dades Gelat, tal com especifica la funció Defaults. La columna Gust conté el valor Maduixa.	{ID: 3, Gust: "Maduixa", Quantitat: 0} S'ha creat l'entrada de Maduixa a la font de dades d'IceCream .

Després d'avaluar les fórmules anteriors, la font de dades acaba amb aquests valors:

Combinar registres (fora d'una font de dades)

Formula	Description	Result
Patch( { Nom: "James", Puntuació: 90 }, { Nom: "Jim", Aprovat: cert } )	Combina dos registres fora d'una font de dades: Els valors de la columna Nom de cada registre no coincideixen. El resultat conté el valor (Jim) del registre més proper al final de la llista d'arguments en comptes del valor (James) del registre més proper a l'inici. El primer registre conté una columna (Puntuació) que no existeix al segon registre. El resultat conté la columna amb el valor (90). El segon registre conté una columna (Aprovat) que no existeix al primer registre. El resultat conté la columna amb el valor (true).	{Nom: "Jim", Puntuació: 90, Aprovat: true}

Modificar o crear un conjunt de registres (en una font de dades)

Quan utilitzes Patch taules en lloc de registres individuals, pots crear o modificar múltiples registres en una sola trucada. El valor de retorn és una taula de registres que correspon un per un amb les taules d'entrada.

Aquest exemple actualitza la quantitat de múltiples sabors a la font de dades d'IceCream alhora:

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

El resultat és una taula amb els registres actualitzats: { ID: 1, Flavor: "Chocolate", Quantity: 300 } i { ID: 2, Flavor: "Vanilla", Quantity: 400 }.

Aquest exemple crea múltiples registres nous utilitzant Defaults:

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

Note

Quan s'utilitza Patch amb taules, el nombre de registres a cada taula de canvi ha de coincidir amb el nombre de registres de la taula base. Si no, es produeix un error.

Per detectar errors quan modifiques diversos registres, utilitza IfError. IfError és el mecanisme preferit i funciona entre hosts Power Fx:

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

Patch amb tipus de columna Dataverse

Els exemples següents s'apropen específicament a fonts de dades Microsoft Dataverse. Les formes dels registres varien segons la font de dades (per exemple, SharePoint i SQL Server tenen formats diferents).

Columna d'elecció: Per establir una columna Elecció, utilitza directament el valor d'enum. Aquest exemple estableix una columna d'elecció d'Estat en una taula de Comptes :

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

Columna de consulta: Per establir una columna de cerca, proporciona un registre amb la clau primària de la taula relacionada. Aquest exemple estableix la cerca de Contacte Primari en un registre de Comptes :

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

Note

Aquests exemples de tipus columna són específics de Dataverse. Altres fonts de dades, com SharePoint o SQL Server, poden requerir formes de registre diferents per a tipus de columnes similars. Consulta la documentació de la teva font de dades específica per al format correcte.

Delegació en fórmules que utilitzen Patch

La Patch funció en si no està subjecta a delegació perquè escriu a la font de dades en lloc de consultar-la. Tanmateix, poden aparèixer advertències de delegació en fórmules que s'utilitzen Patch si la part de selecció de registres de la fórmula (com Filter, LookUp o ForAll) implica una consulta que supera els límits de delegació de la font de dades.

Quan veus un avís de delegació en una fórmula que inclou Patch, comprova si l'advertència s'aplica a les funcions de recuperació de dades i no a Patch ella mateixa. Per a més informació sobre la delegació, vegeu Entén la delegació en una aplicació canvas.

Errors comuns amb la Patch funció

Quan utilitzes la Patch funció, poden produir-se errors a causa de la connectivitat de la font de dades, permisos o conflictes de dades. Utilitza IfError i IsError per detectar errors i respondre adequadament.

• "Error de xarxa quan s'utilitza Patch la funció": Aquest error normalment indica que l'aplicació no pot arribar a la font de dades. Les causes comunes inclouen la pèrdua de la connexió a internet, la font de dades temporalment indisponible o permisos insuficients per a l'usuari actual. Embolica la Patch trucada a IfError per proporcionar un missatge significatiu als usuaris.

• "Existeixen conflictes amb canvis al servidor": Aquest error es produeix quan un altre usuari o procés modifica el mateix registre entre el moment en què l'aplicació llegeix el registre i escriu el canvi. Actualitza la font de dades cridant la funció Refresh i torna a intentar l'operació.

• Errors de permís: Si l'usuari no té permís per crear o modificar registres a la font de dades, la Patch trucada falla. Utilitza IfError per detectar errors relacionats amb permisos i guiar l'usuari.

Per a patrons generals de gestió d'errors, vegeu Maneig d'errors.

Ús de Com o Aquest registre

Utilitza la paraula clau As o ThisRecord a la teva fórmula per evitar un context d'avaluació ambigu.

En l'exemple següent, considerem el primer Lookup de l'afirmació If . (OrderID = A[@OrderID]) s'espera que compari en l'abast OrderIdLookup amb el OrderId de col·lecció A dins l'abast ForAll . En aquest cas, probablement voldràs A[@OrderId] resoldre com a paràmetre local. Però és ambigu.

Actualment, Power Apps interpreta tant el costat esquerre OrderId com el costat dret A[@OrderId] com un camp dins de l'abast Lookup. Per tant, Lookup sempre troba la primera fila a [dbo].[Orders1] perquè la condició és sempre certa (és a dir, la de OrderId qualsevol fila és igual a ella mateixa).

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

Utilitzant Com o Aquest registre

Sempre que sigui possible, utilitza l'operador As o la paraula clau ThisRecord per desambiguar el costat esquerre. Com es recomana en l'escenari anterior.

Quan la teva fórmula utilitza múltiples àmbits amb ForAll, Filter, i Lookup sobre la mateixa font de dades o taula, els paràmetres d'abast poden col·lidir amb el mateix camp en un altre lloc. Per tant, utilitza l'operador As o ThisRecord per resoldre el nom del camp i evitar ambigüitats.

Per exemple, pots utilitzar l'operador As per desambiguar en l'exemple següent.

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

O bé, podeu utilitzar Aquest registre amb el mateix propòsit.

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

Per saber-ne més sobre l'ús de l'operador As i ThisRecord, consulteu l'article Operators .