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 :

Résumé

Utilisez la Patch fonction pour modifier un ou plusieurs enregistrements d’une source de données. La modification de valeurs de champs spécifiques n’affecte pas les 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" } )

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. L’enregistrement de base peut avoir transité par la propriété Items d’une galerie, été placé dans une variable de contexte ou passer par un autre chemin d’accès. Vous pouvez cependant retrouver la source de données initiale de l’enregistrement de base. Cela est important, car l’enregistrement inclut des informations supplémentaires pour faciliter la recherche de l’enregistrement à des fins de 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

Patch peut également être utilisé pour créer ou modifier plusieurs enregistrements avec un seul appel.

Au lieu de transmettre un seul enregistrement de base, une table d’enregistrements de base peut être fournie dans le deuxième argument. Les enregistrements de modification sont également fournis dans une table, chacun correspondant à un enregistrement 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 cette méthode, la valeur de retour est également une table avec chaque enregistrement correspondant à un pour un avec la base et modifiez les enregistrements.

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

Spécifiez au moins deux enregistrements à fusionner. Les enregistrements 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.

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

Syntaxe

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, il est trouvé et modifié. Si le résultat de la fonction Defaults est utilisé, un enregistrement est créé. 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 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.

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, il est trouvé et modifié. Si le résultat de la fonction Defaults est utilisé, un enregistrement est créé. 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 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.

Fusionner des enregistrements

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

• Enregistrements - Obligatoire. Au moins deux enregistrements à fusionner. Les enregistrements 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.

Exemples

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

Dans le cadre de ces exemples, vous allez modifier ou créer un enregistrement dans une source de données nommée IceCream, contenant les données dans cette table et générant automatiquement les valeurs dans la colonneID :

Une fois les formules précédentes évaluées, la source de données se termine avec ces valeurs :

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

Utilisation de As ou de ThisRecord

L’utilisation du mot-clé As ou ThisRecord dans la formule évite un contexte d’évaluation ambigu.

Dans l’exemple ci-dessous, considérez la première recherche dans l’instruction If. (OrderID = A[@OrderID]) est censé comparer le OrderId dans la portée de recherche avec le OrderId de la collection A dans la ForAll portée. Dans ce cas, vous voulez probablement que A[@OrderId] soit résolu en tant que paramètre local. Mais c’est ambigu.

Power Apps interprète actuellement les deux côtés gauche OrderId et droit A[@OrderId] en tant que champs dans la portée de recherche. Par conséquent, la recherche trouvera 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 ThisRecord pour lever l’ambiguïté du côté gauche. Comme cela est recommandé pour le scénario ci-dessus.

Lorsque votre formule utilise plusieurs étendues avec ForAll, Filter et Lookup sur la même source de données ou table, il est possible que les paramètres de portée entrent en collision avec un même champ ailleurs. Par conséquent, il est recommandé d’utiliser 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 lever l’ambiguïté dans l’exemple ci-dessous.

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, voir l’article Opérateurs.