Patch Fonction

S’applique à : Les applications Canvas Copilot Studio Desktop circulent des applications basées sur des modèles et des fonctions Dataverse power Platform CLI

Modifie ou crée un ou plusieurs enregistrements dans une source de données ou fusionne des enregistrements en dehors d’une source de données.

Utilisez la Patch fonction pour modifier des enregistrements dans des situations complexes, par exemple lorsque vous effectuez des mises à jour qui ne nécessitent aucune interaction utilisateur ni utiliser des formulaires qui s’étendent sur plusieurs écrans.

Pour mettre à jour les enregistrements dans un source de données plus facilement pour des modifications simples, utilisez le contrôle Edit form à la place. Quand vous ajoutez un contrôle Edit form, vous fournissez aux utilisateurs un formulaire à remplir, puis vous enregistrez les modifications apportées à une source de données. Pour plus d’informations, consultez Comprendre les formulaires de données.

Regardez cette vidéo pour découvrir comment utiliser la Patch fonction :

Overview

Utilisez la Patch fonction pour modifier un ou plusieurs enregistrements d’une source de données. Il met à jour les valeurs de champs spécifiques sans affecter d’autres propriétés. Par exemple, cette formule modifie le numéro de téléphone pour un client nommé Contoso :

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

Utilisez Patch la fonction Defaults pour créer des enregistrements. Utilisez ce comportement pour créer un seul écran pour la création et la modification des enregistrements. Par exemple, cette formule crée un enregistrement pour un client nommé Contoso :

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

Note

Lorsque vous corrigez une collection en utilisant un enregistrement provenant d’une source de données avec des valeurs par défaut, l’opération de patch met à jour la collection avec les valeurs de correctif spécifiées et les valeurs par défaut de la source de données. La DataSource de l’instruction patch et la fonction DataSource des valeurs par défaut doivent correspondre pour créer un nouvel enregistrement.

Même si vous ne travaillez pas avec une source de données, vous pouvez utiliser Patch pour fusionner deux enregistrements ou plus. Par exemple, cette formule fusionne deux enregistrements en un seul qui identifie à la fois le numéro de téléphone et l’emplacement de Contoso :

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

Description

Modification ou création d’un enregistrement dans une source de données

Pour utiliser cette fonction avec une source de données, spécifiez la source de données, puis spécifiez un enregistrement de base :

  • Pour modifier un enregistrement, l’enregistrement de base doit provenir d’une source de données. Vous pouvez obtenir l’enregistrement de base via la propriété Items d’une galerie, le placer dans une variable contextuelle, ou l’obtenir par un autre chemin. Mais vous devez pouvoir retracer l’enregistrement de base jusqu’à la source de données. Cette exigence est importante car le dossier inclut des informations supplémentaires qui vous aident à le retrouver pour modification.
  • Utilisez la fonction Defaults pour créer un enregistrement de base avec les valeurs par défaut.

Ensuite, spécifiez un ou plusieurs enregistrements de modification contenant chacun de nouvelles valeurs de propriété qui remplacent celles de l’enregistrement de base. Les enregistrements de modification sont traités du début à la fin de la liste d’arguments, les dernières valeurs de propriété remplaçant les précédentes.

La valeur de retour est Patch l’enregistrement que vous avez modifié ou créé. Si vous avez créé un enregistrement, la valeur de retour peut inclure les propriétés générées automatiquement par la source de données. Cependant, la valeur de retour ne fournit pas de valeur pour les champs d’une table liée.

Par exemple, vous utilisez Set(MyAccount, Patch(Accounts, First(Account), 'Account Name': "Example name"));, puis MyAccount.'Primary Contact'.'Full Name'. Vous ne pouvez pas rendre un nom complet dans ce cas. Au lieu de cela, pour accéder aux champs d’une table associée, utilisez une recherche distincte telle que :

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

Lorsque vous mettez à jour une source de données, un ou plusieurs problèmes peuvent survenir. Utilisez IfError et IsError avec la valeur de retour à partir de Patch laquelle détecter et répondre aux erreurs, comme décrit la gestion des erreurs . Vous pouvez également utiliser la fonction Errors pour identifier et examiner les problèmes, comme décrit dans l’article Utilisation des sources de données.

Certaines fonctions connexes sont disponibles, notamment la fonction Update pour remplacer un enregistrement entier et la fonction Collect pour créer un enregistrement. Utilisez la fonction UpdateIf pour modifier des propriétés spécifiques de plusieurs enregistrements selon une condition.

Modification ou création d’un ensemble d’enregistrement dans une source de données

Vous pouvez aussi créer Patch ou modifier plusieurs enregistrements avec un seul appel.

Au lieu de passer un seul enregistrement de base, fournissez un tableau des enregistrements de base dans le second argument. Fournir également des enregistrements de modification dans une table, correspondant un pour un aux enregistrements de base. Le nombre d’enregistrements de chaque table de modifications doit correspondre au nombre d’enregistrements de la table de base.

Lorsque vous utilisez Patch de cette manière, la valeur de retour est aussi une table où chaque enregistrement correspond un pour un aux enregistrements de base et de changement.

Fusion d’enregistrements en dehors d’une source de données

Spécifiez au moins deux enregistrements à fusionner. La fonction traite les enregistrements dans l’ordre du début à la fin de la liste d’arguments, les valeurs de propriété ultérieures prenant le dessus sur les plus anciennes.

Patch retourne l’enregistrement fusionné et ne modifie pas ses arguments ou enregistrements dans des sources de données.

Syntax

Modification ou création d’un enregistrement dans une source de données

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

  • DataSource : obligatoire. La source de données qui contient l’enregistrement que vous souhaitez modifier ou qui contiendra l’enregistrement que vous souhaitez créer.
  • BaseRecord – Obligatoire. L’enregistrement à modifier ou créer. Si l’enregistrement provient d’une source de données, la fonction trouve et modifie l’enregistrement. Si le résultat de Defaults est utilisé, la fonction crée un enregistrement. La source de données de l’instruction patch et la source de données de la fonction Defaults doivent correspondre pour créer un enregistrement.
  • ChangeRecords – Obligatoire. Un ou plusieurs enregistrements contenant des propriétés à modifier dans l’enregistrement de base (BaseRecord). Les processus de fonction changent d’enregistrements dans l’ordre du début à la fin de la liste d’arguments, les valeurs de propriété ultérieures supplantant les valeurs antérieures.

Modification ou création d’un ensemble d’enregistrement dans une source de données

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

  • DataSource : obligatoire. La source de données qui contient les enregistrements que vous souhaitez modifier ou qui contiendra les enregistrements que vous souhaitez créer.
  • BaseRecordTable – Obligatoire. Une table contenant les enregistrements à modifier ou créer. Si l’enregistrement provient d’une source de données, la fonction trouve et modifie l’enregistrement. Si le résultat de Defaults est utilisé, la fonction crée un enregistrement. La source de données de l’instruction patch et la source de données de la fonction Defaults doivent correspondre pour créer un enregistrement.
  • ChangeRecordTables – Obligatoire. Une ou plusieurs tables d’enregistrements qui contiennent des propriétés à modifier pour chaque enregistrement de la table BaseRecordTable. Les processus de fonction changent d’enregistrements dans l’ordre du début à la fin de la liste d’arguments, les valeurs de propriété ultérieures supplantant les valeurs antérieures.

Merge records

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

  • Enregistrements - Obligatoire. Au moins deux enregistrements à fusionner. La fonction traite les enregistrements dans l’ordre du début à la fin de la liste d’arguments, les valeurs de propriété ultérieures prenant le dessus sur les plus anciennes.

Examples

Modification ou création d’un enregistrement (dans une source de données)

Dans ces exemples, vous modifiez ou créez un enregistrement dans une source de données nommée IceCream. La source de données contient les données de ce tableau et génère automatiquement les valeurs dans la colonne ID :

Capture d’écran du tableau d’exemple de source de données IceCream montrant les saveurs et quantités.

Pour créer une version en mémoire de cette source de données afin que vous puissiez essayer ces exemples, évaluez cette formule :

ClearCollect( IceCream,
    { ID: 1, Flavor: "Chocolate", Quantity: 100 },
    { ID: 2, Flavor: "Vanilla", Quantity: 200 }
)
Formula Description Result
Patch( Glace,
LookUp( IceCream, Flavor = « Chocolate » ), { Quantity : 400 } )		 Modifie un enregistrement dans la source de données IceCream :
  • La colonne ID de l’enregistrement à modifier contient la valeur 1. (L’enregistrement Chocolate est associé à cet ID.)
  • La valeur de la colonne Quantity devient 400.
 { ID : 1, Flavor : « Chocolate », Quantity : 400 }

L’entrée Chocolate dans la source de données IceCream est modifiée.
Patch( IceCream, Defaults( IceCream ), { Flavor : « Fraise » } ) Crée un enregistrement dans la source de données IceCream :
  • La colonne ID contient la valeur 3, que la source de données génère automatiquement.
  • La colonne Quantity contient la valeur 0, qui est la valeur par défaut pour cette colonne dans la source de données IceCream, comme spécifié par la fonction Defaults.
  • La colonne Flavor contient la valeur Strawberry.
 { ID : 3, Flavor : « Fraise », Quantity : 0 }

L’entrée Strawberry dans la source de données IceCream est créée.

Après l’évaluation des formules précédentes, la source de données se termine par ces valeurs :

Capture d’écran de la source de données IceCream après l’évaluation des Patch formules.

Fusion d’enregistrements (en dehors d’une source de données)

Formula Description Result
Patch( { Name : « James », Score : 90 }, { Name : « Jim », Passed : true } ) Fusionne deux enregistrements en dehors d’une source de données :
  • Les valeurs de la colonne Name de chaque enregistrement ne correspondent pas. Le résultat contient la valeur (Jim) de l’enregistrement le plus proche de la fin de la liste d’arguments au lieu de la valeur (James) de l’enregistrement le plus proche du début.
  • Le premier enregistrement contient une colonne (Score) qui n’existe pas dans le deuxième enregistrement. Le résultat contient cette colonne avec sa valeur (90).
  • Le deuxième enregistrement contient une colonne (Passed) qui n’existe pas dans le premier enregistrement. Le résultat contient cette colonne avec sa valeur (true).
 { Name : « Jim », Score : 90, Passed : true }

Modifier ou créer un ensemble d’enregistrements (dans une source de données)

Lorsque vous utilisez Patch des tables au lieu d’enregistrements uniques, vous pouvez créer ou modifier plusieurs enregistrements en un seul appel. La valeur de retour est une table d’enregistrements qui correspond un pour un aux tables d’entrée.

Cet exemple met à jour la quantité pour plusieurs saveurs dans la source de données IceCream en même temps :

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

Le résultat est un tableau avec les enregistrements mis à jour : { ID: 1, Flavor: "Chocolate", Quantity: 300 } et { ID: 2, Flavor: "Vanilla", Quantity: 400 }.

Cet exemple crée plusieurs nouveaux enregistrements en utilisant les valeurs par défaut :

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

Note

Lorsque vous utilisez Patch avec des tableaux, le nombre d’enregistrements dans chaque table de modification doit correspondre au nombre d’enregistrements dans la table de base. Dans le cas contraire, une erreur se produit.

Pour détecter les erreurs lors de la modification de plusieurs enregistrements, utilisez IfError. IfError est le mécanisme préféré et fonctionne entre les hôtes Power Fx :

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

Patch avec types de colonnes Dataverse

Les exemples suivants s’appliquent spécifiquement aux sources de données Microsoft Dataverse. Les formes des enregistrements varient selon la source de données (par exemple, SharePoint et SQL Server ont des formats différents).

Colonne de choix : Pour définir une colonne de choix, utilisez directement la valeur d’enum. Cet exemple définit une colonne de choix de statut dans une table des comptes :

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

Colonne de recherche : Pour définir une colonne de recherche, fournissez un enregistrement avec la clé principale de la table correspondante. Cet exemple définit la recherche Primary Contact sur un enregistrement Comptes :

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

Note

Ces exemples de type colonne sont spécifiques à Dataverse. D’autres sources de données, comme SharePoint ou SQL Server, peuvent nécessiter des formes d’enregistrement différentes pour des types de colonnes similaires. Consultez la documentation de votre source de données spécifique pour le format correct.

Délégation dans les formules qui utilisent Patch

La Patch fonction elle-même n’est pas soumise à la délégation car elle écrit sur la source de données plutôt que de l’interroger. Cependant, des avertissements de délégation peuvent apparaître dans des formules qui utilisent Patch si la partie sélection d’enregistrements de la formule (comme Filter, LookUp ou ForAll) implique une requête dépassant les limites de délégation de source de données.

Lorsque vous voyez un avertissement de délégation dans une formule qui inclut Patch, vérifiez si l’avertissement s’applique aux fonctions de récupération des données plutôt qu’à Patch lui-même. Pour plus d’informations sur la délégation, voir Comprendre la délégation dans une application canvas.

Erreurs courantes avec la Patch fonction

Lorsque vous utilisez la Patch fonction, des erreurs peuvent survenir à cause de la connectivité des sources de données, des permissions ou des conflits de données. Utilisez IfError et IsError pour détecter les erreurs et répondre de manière appropriée.

  • « Erreur réseau lors de l’utilisation Patch de la fonction » : Cette erreur indique généralement que l’application ne peut pas atteindre la source de données. Les causes courantes incluent une perte de connexion internet, une source de données temporairement indisponible, ou un manque d’autorisations pour l’utilisateur actuel. Enveloppez l’appel Patch dans IfError pour fournir un message significatif aux utilisateurs.

  • « Des conflits existent avec les modifications sur le serveur » : Cette erreur survient lorsqu’un autre utilisateur ou processus modifie le même enregistrement entre le moment où votre application lit l’enregistrement et écrit le changement. Rafraîchissez la source de données en appelant la fonction de rafraîchissement et réessayez l’opération.

  • Erreurs d’autorisation : Si l’utilisateur n’a pas la permission de créer ou de modifier des enregistrements dans la source de données, l’appel Patch échoue. Utilisez IfError pour détecter les erreurs liées aux permissions et guider l’utilisateur.

Pour des schémas généraux de gestion des erreurs, voir Gestion des erreurs.

Utilisation de As ou de ThisRecord

Utilisez le mot-clé As ou ThisRecord dans votre formule pour éviter un contexte d’évaluation ambigu.

Dans l’exemple suivant, considérons le premier Lookup de l’énoncé If . (OrderID = A[@OrderID]) on s’attend à ce qu’il compare le OrderId dans le Lookup champ d’application avec le OrderId de collection A dans le ForAll champ de retour. Dans ce cas, vous voudrez A[@OrderId] probablement résoudre comme un paramètre local. Mais c’est ambigu.

Power Apps interprète actuellement à la fois le champ gauche OrderId et le côté droit A[@OrderId] comme un champ dans le scope Lookup. Par conséquent, Lookup trouve toujours la première ligne dans [dbo].[Orders1] car la condition est toujours vraie (c’est-à-dire que toute ligne OrderId est égale à elle-même).

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

Utilisation de As ou de ThisRecord

Dans la mesure du possible, utilisez l’opérateur As ou le mot-clé ThisRecord pour déambiguïser le côté gauche. Comme recommandé pour le scénario précédent.

Lorsque votre formule utilise plusieurs portées avec ForAll, Filter, et Lookup sur la même source de données ou table, les paramètres de portée peuvent entrer en collision avec un même champ ailleurs. Par conséquent, utilisez l’opérateur As ou ThisRecord pour résoudre le nom du champ et éviter toute ambiguïté.

Par exemple, vous pouvez utiliser l’opérateur As pour clarifier dans l’exemple suivant.

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

Vous pouvez également utiliser ThisRecord dans le même but.

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

Pour en savoir plus sur l’utilisation de l’opérateur As et de ThisRecord, consultez l’article Operators .

  • Last updated on