PowerApps の Patch 関数Patch function in PowerApps

データ ソース内で 1 つ以上のレコードを変更または作成するか、データ ソースの外部でレコードをマージします。Modifies or creates one or more records in a data source, or merges records outside of a data source.

Patch 関数は、複雑な状況でレコードを変更するために使用します (ユーザーの操作を必要としない更新を実行する場合や、複数の画面にまたがったフォームを使用するなど)。Use the Patch function to modify records in complex situations, such as when you perform updates that require no user interaction or use forms that span multiple screens.

それほど複雑でない状況の場合は、編集フォーム コントロールを使用して、データ ソース内のレコードをより簡単に更新することができます。In less complex situations, you can use the Edit form control to update records in a data source more easily. 編集フォーム コントロールを追加する場合には、データ ソースへの変更を入力し、その後保存するためのフォームをユーザーに提供します。When you add an Edit form control, you provide users with a form to fill in and then save the changes to a data source. 詳しくは、「データ フォームの概要」をご覧ください。For more information, see Understand data forms.

概要Overview

Patch 関数を使用して、データ ソースの 1 つ以上のレコードを変更します。Use the Patch function to modify one or more records of a data source. 特定のフィールドの値が、その他のプロパティに影響を与えることなく変更されます。The values of specific fields are modified without affecting other properties. たとえば、次の式では、Contoso という名前の顧客の電話番号が変更されます。For example, this formula changes the phone number for a customer named Contoso:

Patch( Customers, First( Filter( Customers, Name = "Contoso" ) ), { Phone: “1-212-555-1234” } )Patch( Customers, First( Filter( Customers, Name = "Contoso" ) ), { Phone: “1-212-555-1234” } )

Patch は、レコードを作成するために Defaults 関数と併せて使用します。Use Patch with the Defaults function to create records. この動作は、レコードの作成と編集に使用する単一の画面を構築するのに使用できます。Use this behavior to build a single screen for both creating and editing records. たとえば、次の式では、Contoso という名前の顧客のレコードが作成されます。For example, this formula creates a record for a customer named Contoso:

Patch( Customers, Defaults( Customer ), { Name: “Contoso” } )Patch( Customers, Defaults( Customer ), { Name: “Contoso” } )

データ ソースを使用していない場合でも、Patch を使用して 2 つ以上のレコードをマージすることができます。Even if you're not working with a data source, you can use Patch to merge two or more records. たとえば、次の式では、2 つのレコードがマージされ、Contoso の電話番号と所在地の両方を識別するレコードが作成されます。For example, this formula merges two records into one that identifies both the phone number and the location for Contoso:

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

説明Description

データ ソースのレコードを変更または作成するModify or create a record in a data source

データ ソースに対してこの関数を使用するには、データ ソースを指定し、基本レコードを指定します。To use this function with a data source, specify the data source, and then specify a base record:

  • レコードを変更する場合、基本レコードはデータ ソースからのものである必要があります。To modify a record, the base record needs to have come from a data source. 基本レコードは、ギャラリーの Items プロパティから取得されてコンテキスト変数内に配置されることも、他のパスを通じて取得されることもあります。The base record may have come through a gallery's Items property, been placed in a context variable, or come through some other path. しかし、基本レコードは、データ ソースまで追跡可能である必要があります。But you should be able to trace the base record back to the data source. レコードには、変更する際にそのレコードを再度特定するのに役立つ情報を追加するため、これは重要です。This is important as the record will include additional information to help find the record again for modification.
  • レコードを作成する際は、Defaults 関数を使用して既定値で基本レコードを作成します。To create a record, use the Defaults function to create a base record with default values.

次に、1 つ以上の変更レコードを指定します。各レコードには、基本レコード内のプロパティ値を上書きする新しいプロパティ値が含まれます。Then specify one or more change records, each of which contains new property values that override property values in the base record. 変更レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。Change records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

Patch の戻り値は、変更または作成したレコードです。The return value of Patch is the record that you modified or created. レコードを作成した場合、戻り値にはデータ ソースによって自動的に生成されたプロパティが含まれる場合があります。If you created a record, the return value may include properties that the data source generated automatically.

データ ソースを更新するとき、1 つまたは複数の問題が発生する場合があります。When you update a data source, one or more issues may arise. データ ソースの利用に関する記事で説明されているとおり、問題の特定と調査には Errors 関数を使用します。Use the Errors function to identify and examine issues, as Working with Data Sources describes.

関連する関数として、レコード全体の置き換えに使用できる Update 関数や、レコードの作成に使用できる Collect 関数などがあります。Related functions include the Update function, which you can use to replace an entire record, and the Collect function, which you can use to create a record. UpdateIf 関数を使用すると、条件に基づいて複数のレコードの特定のプロパティを変更できます。You can use the UpdateIf function to modify specific properties of multiple records based on a condition.

データ ソースのレコード セットを変更または作成するModify or create a set of records in a data source

Patch は、1 回の呼び出しで複数のレコードを作成または変更するときにも使用できます。Patch can also be used to create or modify multiple records with a single call.

基本レコードを 1 つ渡す代わりに、2 番目の引数で基本レコードのテーブルを渡せます。Instead of passing a single base record, a table of base records can be provided in the second argument. 変更レコードもテーブルで渡され、基本レコードに一対一で対応します。Change records are provided in a table as well, corresponding one-for-one with the base records. 各変更テーブル内のレコードの数は、基本テーブル内のレコードの数と同じである必要があります。The number of records in each change table must be the same as the number of records in the base table.

この方法で Patch を使用した場合、戻り値もテーブルになり、その各レコードは基本レコードと変更レコードに一対一で対応します。When using Patch in this manner, the return value is also a table with each record corresponding one-for-one with the base and change records.

データ ソースの外部でレコードをマージするMerge records outside of a data source

マージする 2 つ以上のレコードを指定します。Specify two or more records that you want to merge. レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。Records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

Patch はマージされたレコードを返します。引数またはデータ ソース内のレコードは変更されません。Patch returns the merged record and doesn't modify its arguments or records in any data sources.

構文Syntax

データ ソースのレコードを変更または作成するModify or create a record in a data source

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

  • DataSource – 必須。DataSource – Required. 変更するレコードを含むデータ ソースまたはこれから作成するレコードを含むデータ ソース。The data source that contains the record that you want to modify or will contain the record that you want to create.
  • BaseRecord – 必須。BaseRecord – Required. 変更または作成するレコード。The record to modify or create. レコードがデータ ソースからのものだった場合、レコードが検出され、変更されます。If the record came from a data source, the record is found and modified. Defaults の結果を使用した場合は、レコードが作成されます。If the result of Defaults is used, a record is created.
  • ChangeRecord(s) – 必須。ChangeRecord(s) – Required. BaseRecord 内で変更するプロパティを含む、1 つまたは複数のレコード。One or more records that contain properties to modify in the BaseRecord. 変更レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。Change records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

データ ソースのレコード セットを変更または作成するModify or create a set of records in a data source

Patch( DataSource, BaseRecordsTable, ChageRecordTable1, [, ChangeRecordTable2, …Patch( DataSource, BaseRecordsTable, ChageRecordTable1, [, ChangeRecordTable2, … ] )] )

  • DataSource – 必須。DataSource – Required. 変更するレコードを含むデータ ソースまたはこれから作成するレコードを含むデータ ソース。The data source that contains the records that you want to modify or will contain the records that you want to create.
  • BaseRecordTable – 必須。BaseRecordTable – Required. 変更または作成するレコードのテーブル。A table of records to modify or create. レコードがデータ ソースからのものだった場合、レコードが検出され、変更されます。If the record came from a data source, the record is found and modified. Defaults の結果を使用した場合は、レコードが作成されます。If the result of Defaults is used, a record is created.
  • ChangeRecordTable(s) – 必須。ChangeRecordTable(s) – Required. BaseRecordTable の各レコードで変更するプロパティを含む、1 つまたは複数のレコード テーブル。One or more tables of records that contain properties to modify for each record of the BaseRecordTable. 変更レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。Change records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

レコードをマージするMerge records

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

  • Record(s) - 必須。Record(s) - Required. 少なくとも 2 つ以上の、マージするレコード。At least two records that you want to merge. レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。Records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

Examples

(データ ソースの) レコードを変更または作成するModify or create a record (in a data source)

これらの例では、IceCream というデータ ソースのレコードを変更または作成します。このデータ ソースは次のテーブルのデータを含み、ID 内の値を自動的に生成します。In these examples, you'll modify or create a record in a data source, named IceCream, that contains the data in this table and automatically generates the values in the ID column:

数式Formula 説明Description 結果Result
Patch( IceCream,
First( Filter( IceCream, Flavor = "Chocolate" ) ), { Quantity: 400 } )
Patch( IceCream,
First( Filter( IceCream, Flavor = "Chocolate" ) ), { Quantity: 400 } )
IceCream データ ソース内のレコードを変更します。Modifies a record in the IceCream data source:
  • 変更するレコードの ID 列には値 1 が含まれます The ID column of the record to modify contains the value of 1. (Chocolate レコードの ID がこれです)。(The Chocolate record has that ID.)
  • Quantity 列の値が 400 に変更されます。The value in the Quantity column changes to 400.
{ ID: 1, Flavor: "Chocolate", Quantity: 400 }{ ID: 1, Flavor: "Chocolate", Quantity: 400 }

IceCream データ ソースの Chocolate エントリが変更されています。The Chocolate entry in the IceCream data source has been modified.
Patch( IceCream, Defaults( IceCream ), { Flavor: "Strawberry" } )Patch( IceCream, Defaults( IceCream ), { Flavor: “Strawberry” } ) IceCream データ ソース内のレコードを作成します。Creates a record in the IceCream data source:
  • ID 列には値 3 が含まれます。これはデータ ソースが自動的に生成するものです。The ID column contains the value 3, which the data source generates automatically.
  • Quantity 列には 0 が含まれます。これは Defaults 関数で指定するとおり、IceCream データ ソースにおけるこの列の既定値です。The Quantity column contains 0, which is the default value for that column in the IceCream data source, as the Defaults function specifies.
  • Flavor 列には Strawberry という値が含まれます。The Flavor column contains the value of Strawberry.
{ ID: 3, Flavor: "Strawberry", Quantity: 0 }{ ID: 3, Flavor: “Strawberry”, Quantity: 0 }

IceCream データ ソースの Strawberry エントリが作成されています。The Strawberry entry in the IceCream data source has been created.

前の数式が評価された後、データ ソースはこれらの値で終了します。After the previous formulas have been evaluated, the data source ends with these values:

(データ ソースの外部で) レコードをマージするMerge records (outside of a data source)

数式Formula 説明Description 結果Result
Patch( { Name: "James", Score: 90 }, { Name: "Jim", Passed: true } )Patch( { Name: "James", Score: 90 }, { Name: "Jim", Passed: true } ) データ ソースの外部で 2 つのレコードをマージします。Merges two records outside of a data source:
  • 各レコードの Name 列の値は一致しません。The values in the Name column of each record don't match. 結果には、引数リストの先頭に近いレコードの値 (James) ではなく、末尾に近いレコードの値 (Jim) が含まれます。The result contains the value (Jim) in the record that's closer to the end of the argument list instead of the value (James) in the record that's closer to the start.
  • 最初のレコードには、2 番目のレコードには存在しない列 (Score) が含まれます。The first record contains a column (Score) that doesn't exist in the second record. 結果には、その列とその値 (90) が含まれます。The result contains that column with its value (90).
  • 2 番目のレコードには、最初のレコードには存在しない列 (Passed) が含まれます。The second record contains a column (Passed) that doesn't exist in the first record. 結果には、その列とその値 (true) が含まれます。The result contains that column with its value (true).
{ Name: "Jim", Score: 90, Passed: true }{ Name: "Jim", Score: 90, Passed: true }