Fonction Patch

S’applique à : Applications canevas  Applications pilotées par modèle Power Platform CLI  Flux Bureau

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 fonction Patch pour modifier des enregistrements dans des situations complexes, comme quand vous effectuez des mises à jour qui ne nécessitent aucune interaction utilisateur ou qui utilisent des formulaires occupant 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 fonction Patch :

Résumé

Utilisez la fonction Patch 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, First( Filter( Customers, Name = "Contoso" ) ), { Phone: "1-212-555-1234" } )

Utilisez la fonction Patch avec 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 la fonction 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 provenir de la propriété Items d’une galerie, avoir été placé dans une variable de contexte ou provenir d’une autre source. Vous pouvez cependant retrouver la source de données initiale de l’enregistrement de base. En effet, l’enregistrement inclut des informations supplémentaires simplifiant la recherche de l’enregistrement en vue de sa 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 renvoyée par la fonction Patch est l’enregistrement que vous avez modifié ou créé. Si vous avez créé un enregistrement, la valeur renvoyée peut inclure des propriétés que la source de données a générées automatiquement. 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'

La mise à jour d’une source de données peut entraîner un ou plusieurs problèmes. Utilisez IfError et IsError avec la valeur de retour de Patch pour détecter et répondre aux erreurs, comme le 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 la fonction Patch de cette manière, la valeur renvoyée est également une table dont chaque enregistrement de base correspond à un enregistrement de modification.

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 renvoie l’enregistrement fusionné et ne modifie pas ses arguments ni ses enregistrements dans aucune source 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éé.
• 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éé.
• 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( Enregistrement1, Enregistrement2 [, …] )

• 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 colonne ID :

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.