Patch-Funktion

Gilt für: Canvas-Apps Copilot Studio Desktop flows Modellgesteuerte Apps Power Platform CLI Dataverse-Funktionen

Ändert oder erstellt einen oder mehrere Datensätze in einer Datenquelle oder verbindet Datensätze außerhalb einer Datenquelle.

Verwenden Sie die Patch Funktion, um Datensätze in komplexen Situationen zu ändern, z. B. wenn Sie Aktualisierungen ausführen, die keine Benutzerinteraktion erfordern, oder Formulare verwenden, die sich über mehrere Bildschirme erstrecken.

Verwenden Sie stattdessen das Edit form-Steuerelement, um Datensätze in einer Datenquelle schneller und einfacher zu aktualisieren. Wenn Sie ein Edit form-Steuerelement hinzufügen, geben Sie Benutzern ein Formular an die Hand, das sie ausfüllen und dessen Änderungen sie dann in einer Datenquelle speichern können. Weitere Informationen finden Sie unter Grundlegendes zu Datenformularen.

Schauen Sie sich dieses Video an, um zu erfahren, wie Sie die Patch Funktion verwenden:

Overview

Verwenden Sie die Patch Funktion, um einen oder mehrere Datensätze einer Datenquelle zu ändern. Es aktualisiert die Werte bestimmter Felder , ohne andere Eigenschaften zu beeinflussen. Beispielsweise ändert diese Formel die Telefonnummer für einen Kunden mit dem Namen Contoso:

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

Wird mit der Patch zum Erstellen von Datensätzen verwendet. Verwenden Sie dieses Verhalten zum Erstellen eines kombinierten Bildschirms für die Erstellung und Bearbeitung von Datensätzen. Beispielsweise erstellt diese Formel einen Datensatz für einen Kunden mit dem Namen Contoso:

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

Auch wenn Sie nicht mit einer Datenquelle arbeiten, können Patch Sie zwei oder mehr Datensätze zusammenführen. Diese Formel führt beispielsweise zwei Datensätze zu einem zusammen, der sowohl die Telefonnummer als auch den Standort von Contoso angibt:

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

Description

Ändern oder Erstellen eines Datensatzes in einer Datenquelle

Um diese Funktion mit einer Datenquelle zu verwenden, geben Sie zunächst die Datenquelle an und anschließend einen Basisdatensatz:

• Um einen Datensatz zu ändern, muss der Basisdatensatz aus einer Datenquelle stammen. Du könntest den Basiseintrag über die Items-Eigenschaft einer Galerie bekommen, ihn in eine Kontextvariable einordnen oder über einen anderen Pfad erhalten. Aber du musst in der Lage sein, den Basisdatensatz bis zur Datenquelle zurückverfolgen zu können. Diese Anforderung ist wichtig, da der Datensatz zusätzliche Informationen enthält, die Ihnen helfen, den Akten zur Bearbeitung wiederzufinden.
• Zum Erstellen eines Datensatzes verwenden Sie die Defaults-Funktion und erstellen einen Basisdatensatz mit Standardwerten.

Geben Sie anschließend einen oder mehrere Änderungsdatensätze mit jeweils neuen Eigenschaftswerten an, die die Eigenschaftswerte im Basisdatensatz überschreiben. Änderungsdatensätze werden nacheinander vom Anfang bis zum Ende der Argumenteliste verarbeitet, wobei spätere Eigenschaftswerte frühere Versionen überschreiben.

Der Rückgabewert Patch ist der Datensatz, den Sie geändert oder erstellt haben. Wenn Sie einen Datensatz erstellt haben, enthält der Rückgabewert möglicherweise Eigenschaften, die die Datenquelle automatisch generiert hat. Der Rückgabewert stellt jedoch keinen Wert für Felder einer verknüpften Tabelle bereit.

Zum Beispiel verwenden Sie Set(MyAccount, Patch(Accounts, First(Account), 'Account Name': "Example name")); und dann MyAccount.'Primary Contact'.'Full Name'. In diesem Fall können Sie keinen vollständigen Namen angeben. Um auf die Felder einer verknüpften Tabelle zuzugreifen, verwenden Sie stattdessen eine separate Suche wie:

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

Wenn Sie eine Datenquelle aktualisieren, kann ein oder mehrere Probleme auftreten. Verwenden Sie IfError und IsError mit dem Rückgabewert, von Patch dem Fehler erkannt und auf Fehler reagiert werden, wie die Fehlerbehandlung beschreibt. Sie können auch die Errors-Funktion verwenden, um Probleme zu identifizieren und zu untersuchen, wie unter Arbeiten mit Datenquellen beschrieben.

Zu den verwandten Funktionen gehören die Update-Funktion, die Sie verwenden können, um einen vollständiger Datensatz zu ersetzen, und die Collect-Funktion zum Erstellen eines Datensatzes.. Mithilfe der UpdateIf-Funktion können Sie bestimmte Eigenschaften von mehreren Datensätzen auf der Grundlage einer Bedingung ändern.

Ändern oder Erstellen einer Gruppe von Datensätzen in einer Datenquelle

Du kannst sie auch verwenden Patch , um mehrere Datensätze mit einem einzigen Anruf zu erstellen oder zu verändern.

Anstatt einen einzelnen Basisdatensatz zu übergeben, stellen Sie im zweiten Argument eine Tabelle der Basisdatensätze bereit. Stellen Sie auch Änderungsdatensätze in einer Tabelle bereit, die den Basisdatensätzen entspricht. Die Anzahl der Datensätze in jeder Änderungstabelle muss mit der Anzahl der Datensätze in der Basistabelle identisch sein.

Wenn Sie auf diese Weise verwenden Patch , ist der Rückgabewert auch eine Tabelle, wobei jeder Datensatz eins zu eins mit den Basis- und Änderungsdatensätzen übereinstimmt.

Zusammenführen von Datensätzen außerhalb einer Datenquelle

Geben Sie zwei oder mehr Datensätze an, die Sie zusammenführen möchten. Die Funktion verarbeitet Datensätze in der Reihenfolge vom Anfang der Argumentliste bis zum Ende, wobei spätere Eigenschaftswerte die früheren überlagern.

Patch gibt den zusammengeführten Datensatz zurück und ändert seine Argumente oder Datensätze in keiner Datenquelle.

Syntax

Ändern oder Erstellen eines Datensatzes in einer Datenquelle

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

• DataSource – Erforderlich. Die Datenquelle, die den zu ändernden Datensatz enthält oder für die Sie einen Datensatz erstellen möchten.
• BaseRecord – Erforderlich. Der zu ändernde oder zu erstellende Datensatz. Wenn der Datensatz aus einer Datenquelle stammt, findet und ändert die Funktion den Datensatz. Wenn das Ergebnis von Defaults verwendet wird, erstellt die Funktion einen Datensatz. Die Datenquelle der Patch-Anweisung und der DataSource der Defaults-Funktion muss übereinstimmen, um einen neuen Datensatz zu erstellen.
• ChangeRecords – Erforderlich. Mindestens ein Datensatz, der Eigenschaften enthält, die für jeden Datensatz im BaseRecord geändert werden sollen. Die Funktion verarbeitet die Änderungsdatensätze in der Reihenfolge vom Anfang der Argumentliste bis zum Ende, wobei spätere Eigenschaftswerte frühere überlagern.

Ändern oder Erstellen einer Gruppe von Datensätzen in einer Datenquelle

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

• DataSource – Erforderlich. Die Datenquelle mit den zu ändernden Datensätzen oder für die Sie Datensätze erstellen möchten.
• BaseRecordTable – Erforderlich. Eine Tabelle mit zu ändernden oder zu erstellenden Datensätzen. Wenn der Datensatz aus einer Datenquelle stammt, findet und ändert die Funktion den Datensatz. Wenn das Ergebnis von Defaults verwendet wird, erstellt die Funktion einen Datensatz. Die Datenquelle der Patch-Anweisung und der DataSource der Defaults-Funktion muss übereinstimmen, um einen neuen Datensatz zu erstellen.
• ChangeRecordTables – Erforderlich. Mindestens eine Tabelle von Datensätzen mit Eigenschaften, die für jeden Datensatz von BaseRecordTable geändert werden sollen. Die Funktion verarbeitet die Änderungsdatensätze in der Reihenfolge vom Anfang der Argumentliste bis zum Ende, wobei spätere Eigenschaftswerte frühere überlagern.

Merge records

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

• Datensätze – Erforderlich. Mindestens zwei Datensätze, die Sie zusammenführen möchten. Die Funktion verarbeitet Datensätze in der Reihenfolge vom Anfang der Argumentliste bis zum Ende, wobei spätere Eigenschaftswerte frühere überlagern.

Examples

Ändern oder Erstellen eines Datensatzes (in einer Datenquelle)

In diesen Beispielen modifizieren oder erstellen Sie einen Datensatz in einer Datenquelle namens IceCream. Die Datenquelle enthält die Daten in dieser Tabelle und generiert automatisch die Werte in der ID-Spalte:

Um eine In-Memory-Version dieser Datenquelle zu erstellen, damit Sie diese Beispiele ausprobieren können, bewerten Sie diese Formel:

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

Nachdem die vorherigen Formeln ausgewertet wurden, endet die Datenquelle mit diesen Werten:

Zusammenführen von Datensätzen (außerhalb einer Datenquelle)

Ändern oder erstellen Sie einen Datensatz (in einer Datenquelle)

Wenn du mit Tabellen statt einzelner Datensätze verwendest Patch , kannst du mehrere Datensätze in einem einzigen Aufruf erstellen oder ändern. Der Rückgabewert ist eine Tabelle von Datensätzen, die eins zu eins mit den Eingabetabellen übereinstimmt.

Dieses Beispiel aktualisiert die Menge für mehrere Geschmacksrichtungen in der Eiscreme-Datenquelle gleichzeitig:

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

Das Ergebnis ist eine Tabelle mit den aktualisierten Datensätzen: { ID: 1, Flavor: "Chocolate", Quantity: 300 } und { ID: 2, Flavor: "Vanilla", Quantity: 400 }.

Dieses Beispiel erstellt mehrere neue Datensätze mit Defaults:

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

Um Fehler zu erkennen, wenn Sie mehrere Datensätze ändern, verwenden Sie IfError. IfError ist der bevorzugte Mechanismus und funktioniert über Power Fx-Hosts hinweg:

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

Patch mit Dataverse-Spaltentypen

Die folgenden Beispiele gelten speziell für Microsoft Dataverse Datenquellen. Datensatzformen variieren je nach Datenquelle (zum Beispiel haben SharePoint und SQL Server unterschiedliche Formate).

Auswahlspalte: Um eine Choice-Spalte zu setzen, verwenden Sie direkt den Enum-Wert. Dieses Beispiel setzt eine Statuswahl-Spalte in einer Konto-Tabelle:

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

Suchspalte: Um eine Suchspalte zu setzen, geben Sie einen Datensatz mit dem Primärschlüssel der zugehörigen Tabelle an. Dieses Beispiel setzt die Primärkontakt-Abfrage in einem Buchhaltungsdatensatz :

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

Delegation in Formeln, die verwenden Patch

Die Patch Funktion selbst unterliegt nicht der Delegation , da sie zur Datenquelle schreibt, anstatt sie abzufragen. Allerdings können Delegationswarnungen in Formeln erscheinen, die verwendet werden Patch , wenn der Datensatzauswahlteil der Formel (wie Filter, LookUp oder ForAll) eine Abfrage beinhaltet, die die Datenquellendelegierungsgrenzen überschreitet.

Wenn du eine Delegationswarnung in einer Formel siehst, die , Patchprüfe, ob die Warnung für die Datenabruffunktionen und Patch nicht für sich selbst gilt. Weitere Informationen zur Delegation finden Sie unter Delegation verstehen in einer Canvas-App.

Häufige Fehler mit der Patch Funktion

Wenn Sie die Patch Funktion verwenden, können Fehler auftreten, bedingt durch die Verbindung der Datenquellen, Berechtigungen oder Datenkonflikte. Verwenden Sie IfError und IsError, um Fehler zu erkennen und angemessen zu reagieren.

• "Netzwerkfehler bei Verwendung Patch der Funktion": Dieser Fehler zeigt typischerweise an, dass die App die Datenquelle nicht erreichen kann. Häufige Ursachen sind eine verlorene Internetverbindung, vorübergehend nicht verfügbare Datenquelle oder unzureichende Berechtigungen für den aktuellen Nutzer. Wickle den Patch Aufruf in IfError, um den Nutzern eine aussagekräftige Nachricht zu geben.

• "Es gibt Konflikte mit Änderungen auf dem Server": Dieser Fehler tritt auf, wenn ein anderer Benutzer oder Prozess denselben Datensatz zwischen dem Zeitpunkt ändert, an dem Ihre App den Datensatz liest und die Änderung schreibt. Aktualisieren Sie die Datenquelle, indem Sie die Aktualisierungsfunktion aufrufen, und versuchen Sie die Operation erneut.

• Berechtigungsfehler: Wenn der Benutzer keine Berechtigung hat, Datensätze in der Datenquelle zu erstellen oder zu ändern, schlägt der Patch Aufruf fehl. Verwenden Sie IfError , um berechtigungsbezogene Fehler zu erkennen und den Benutzer zu führen.

Für allgemeine Fehlerbehandlungsmuster siehe Fehlerbehandlung.

Verwendung von As oder ThisRecord

Verwenden Sie in Ihrer Formel das As- oder ThisRecord-Stichwort , um mehrdeutige Bewertungskontexte zu vermeiden.

Im folgenden Beispiel betrachten wir das erste Lookup in der If Aussage. (OrderID = A[@OrderID]) Es wird erwartet, dass die OrderId im Umfang Lookup mit der OrderId Sammlung A im ForAll Umfang verglichen wird. In diesem Fall möchtest A[@OrderId] du wahrscheinlich als lokalen Parameter auflösen. Aber es ist mehrdeutig.

Power Apps interpretiert derzeit sowohl die linke Seite OrderId als auch die rechte Seite A[@OrderId] als Feld im Scope Lookup. Daher findet immer Lookup die erste Zeile in , [dbo].[Orders1] weil die Bedingung immer wahr ist (das heißt, jede Zeile OrderId ist gleich sich selbst).

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

Wendung von As oder ThisRecord

Wann immer möglich, verwenden Sie den As-Operator oder das ThisRecord-Schlüsselwort , um die linke Seite zu unterscheiden. Wie für das vorherige Szenario empfohlen.

Wenn deine Formel mehrere Scopes mit ForAll, Filter, und Lookup auf derselben Datenquelle oder Tabelle verwendet, könnten Scope-Parameter mit demselben Feld an anderer Stelle kollidieren. Verwenden Sie daher den As-Operator oder ThisRecord, um den Feldnamen zu lösen und Mehrdeutigkeiten zu vermeiden.

Zum Beispiel können Sie den Operatoren As verwenden, um im folgenden Beispiel zu disambiguieren.

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

Alternativ können Sie ThisRecord für denselben Zweck verwenden.

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

Um mehr über die Verwendung des As-Operators und ThisRecord zu erfahren, siehe den Artikel Operators .