Patch 関数

適用対象: キャンバス アプリ Copilot Studio デスクトップ フロー モデル駆動型アプリ Power Platform CLI Dataverse 関数

データ ソース 内で 1 つ以上の レコード を変更または作成するか、データ ソースの外部でレコードをマージします。

Patch関数を使用して、ユーザー操作を必要としない更新を行ったり、複数の画面にまたがるフォームを使用したりする場合など、複雑な状況でレコードを変更できます。

簡単な変更のためにデータ ソースのレコードを簡単に更新するには、代わりに Edit form コントロールを使用します。 Edit form コントロールを追加する場合には、データ ソースへの変更を入力し、その後保存するためのフォームをユーザーに提供します。 詳細については、データ フォームの概要 を参照してください。

Patch関数の使用方法については、次のビデオをご覧ください。

概要

Patch関数を使用して、データ ソースの 1 つ以上のレコードを変更します。 特定の フィールド の値が、その他のプロパティに影響を与えることなく変更されます。 たとえば、次の式では、Contoso という名前の顧客の電話番号が変更されます。

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

レコードを作成するには、defaults 関数でPatchを使用します。 この動作は、レコードの作成と編集に使用する 単一の画面 を構築するのに使用できます。 たとえば、次の式では、Contoso という名前の顧客のレコードが作成されます。

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

データ ソースを操作していない場合でも、 Patch を使用して 2 つ以上のレコードをマージできます。 たとえば、次の式では、2 つのレコードがマージされ、Contoso の電話番号と所在地の両方を識別するレコードが作成されます。

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

内容

データ ソースのレコードを変更または作成する

データ ソースに対してこの関数を使用するには、データ ソースを指定し、基本レコードを指定します。

• レコードを変更する場合、基本レコードはデータ ソースからのものである必要があります。 基本レコードは、ギャラリーの Items プロパティを介して取得されたか、 コンテキスト変数に配置されているか、または他のパスを経由している可能性があります。 しかし、基本レコードはデータ ソースまで追跡することができます。 レコードには変更のためにレコードをもう一度見つけるのに役立つ追加情報が含まれているので、これは重要です。
• レコードを作成する際は、Defaults 関数を使用して既定値で基本レコードを作成します。

次に、1 つ以上の変更レコードを指定します。各レコードには、基本レコード内のプロパティ値をオーバーライドする新しいプロパティ値が含まれます。 変更レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。

Patchの戻り値は、変更または作成したレコードです。 レコードを作成した場合、戻り値には、データ ソースによって自動的に生成されるプロパティが含まれる場合があります。 ただし、戻り値は、関連するテーブルのフィールドの値を提供しません。

たとえば、Set(MyAccount, Patch(Accounts, First(Account), 'Account Name': "Example name")); を使用し、その後 MyAccount.'Primary Contact'.'Full Name' を使用します。 この場合、フル ネームを取得することはできません。 代わりに、関連するテーブルのフィールドにアクセスするには、次のような別のルックアップを使用します。

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

データ ソースを更新すると、1 つ以上の問題が発生する可能性があります。 エラー処理で説明されているように、エラーを検出して対応するには、Patchからの戻り値と共に IfError と IsError を使用します。 データ ソースの利用に関する記事で説明されているとおり、問題の特定と調査には Errors 関数を使用することもできます。

関連する関数に、レコード全体を置き換える Update 関数および、レコードを作成する Collect 関数が含まれます。 UpdateIf 関数を使用し、条件に基づいて複数のレコードの特定のプロパティを変更できます。

データ ソースのレコード セットを変更または作成する

Patch を使用して、1 回の呼び出しで複数のレコードを作成または変更することもできます。

基本レコードを 1 つ渡す代わりに、2 番目の引数で基本レコードのテーブルを渡せます。 変更レコードもテーブルで渡され、基本レコードに一対一で対応します。 各変更テーブル内のレコードの数は、基本テーブル内のレコードの数と同じである必要があります。

この方法で Patch を使用する場合、戻り値は、ベース レコードと変更レコードに対応する 1 対 1 の各レコードを含むテーブルでもあります。

データ ソースの外部でレコードをマージする

マージする 2 つ以上のレコードを指定します。 レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。

Patch はマージされたレコードを返し、データ ソース内の引数またはレコードは変更しません。

構文

データ ソースのレコードを変更または作成する

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

• DataSource – 必須。 変更するレコードを含むデータ ソースまたはこれから作成するレコードを含むデータ ソース。
• BaseRecord – 必須。 変更または作成するレコード。 レコードがデータ ソースからのものだった場合、レコードが検出され、変更されます。 Defaults の結果を使用した場合、レコードが作成されます。 新しいレコードを作成するには、patch ステートメントのデータソースと Defaults 関数のデータソースが一致している必要があります。
• ChangeRecords – 必須。 BaseRecord 内で変更するプロパティを含む、1 つ以上のレコード。 変更レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。

データ ソースのレコード セットを変更または作成する

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

• DataSource – 必須。 変更するレコードを含むデータ ソースまたはこれから作成するレコードを含むデータ ソース。
• BaseRecordTable – 必須。 変更または作成するレコードのテーブル。 レコードがデータ ソースからのものだった場合、レコードが検出され、変更されます。 Defaults の結果を使用した場合、レコードが作成されます。 新しいレコードを作成するには、patch ステートメントのデータソースと Defaults 関数のデータソースが一致している必要があります。
• ChangeRecordTables – 必須。 BaseRecordTable の各レコードで変更するプロパティを含む、1 つ以上のレコード テーブル。 変更レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。

レコードの統合

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

• 記録 - 必須。 少なくとも 2 つ以上の、マージするレコード。 レコードは、引数リストの先頭から末尾まで順に処理されます。その際、以前のプロパティ値は後のプロパティ値によって上書きされます。

例

(データ ソース 内の) レコードを変更または作成する

これらの例では、IceCream というデータ ソースのレコードを変更または作成します。このデータ ソースは次の テーブル のデータを含み、ID列内 の値を自動的に生成します。

前の数式が評価された後、データ ソースはこれらの値で終了します。

(データ ソースの外部で) レコードをマージする

As または ThisRecord の使用

式で As または ThisRecord キーワードを使用すると、あいまいな評価コンテキストを回避します。

以下の例では、If ステートメントの最初のルックアップについて考えてみます。 (OrderID = A[@OrderID]) ルックアップ スコープ内の OrderId と、スコープ内の OrderId コレクション A を比較することが期待されます。 ForAll この場合、A[@OrderId] をローカル パラメータとして解決する必要があります。 しかし、それはあいまいです。

Power Apps は現在、左側の OrderId と右側の A[@OrderId] の両方をルックアップ スコープのフィールドとして解釈します。 したがって、条件が常に真 (つまり、どの行の [dbo].[Orders1] もそれ自体に等しい) であるため、ルックアップでは常に OrderId の最初の行が検索されます。

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

As または ThisRecord の使用

可能な限り、As 演算子または ThisRecord を使用して、左側を明確にします。 上記のシナリオでは、 が推奨されます。

式で同じデータ ソースまたはテーブルの ForAll、Filter、および Lookup で複数のスコープを使用する場合、スコープ パラメーターが他の場所の同じフィールドと衝突する可能性があります。 したがって、As 演算子または ThisRecord を使用して、フィールド名を解決し、あいまいさを回避することをお勧めします。

たとえば、以下の例では As 演算子を使用して曖昧さを解消することができます。

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

または、ThisRecord を同じ目的で使用できます。

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

As 演算子と ThisRecord の使用法の詳細については、演算子 の記事を参照してください。