基本操作

Power Apps Patch関数で新規レコードを作成する｜Defaults・列型別の値指定パターン完全解説

Power Apps Patch関数で新規レコードを作成する｜Defaults・列型別の値指定パターン完全解説

フォームを使わずにSharePointにデータを保存したいなら、Patch関数が答えです。Patch関数は列の型さえ意識すれば難しくありません。ただ最初のうちは型エラーで詰まる人が多いので、基本の構造から丁寧に解説します。

Patch関数の3つの引数

Patch関数は次の3つの引数で構成されています。

Patch( データソース, 対象レコード, 更新する列と値 )

「どのテーブルに」「新規か更新か」「何を書くか」という3点セットです。この構造さえ頭に入れておけば、あとは列の型に合わせた値を渡すだけです。

第1引数：データソース

保存先のテーブルを指定します。SharePointリストなら接続時の名前（例：Employees）をそのまま書きます。アプリにデータソースを追加してあれば自動補完が効くので、名前を丸暗記する必要はありません。データソースの追加方法がわからない場合は、SharePoint CRUDの基本パターンを先に読んでみてください。

第2引数：対象レコード

新規レコードを作るか、既存レコードを更新するかはここで決まります。新規作成には Defaults(テーブル名) を使います。Defaultsとは「まだ何も書いていない新規レコードの雛形」を意味します。料理にたとえるなら、まだ何も書いていない注文票を1枚取り出す操作です。既存レコードを更新したい場合はGallery.SelectedやvarRecordを使いますが、それは既存レコード更新編で解説します。

第3引数：更新する列と値

{ 列名: 値, 列名: 値 } の形で書きます。波括弧で囲むことを忘れないでください。Power Appsのレコードは常にこの波括弧形式で表現されます。列名は自動補完が効くので、最初の数文字を打てば候補が出てきます。補完候補を活用するとスペルミスも防げて一石二鳥です。

まずハードコードで動かしてみる

Patch関数を初めて使うとき、やるべきことはまずハードコードで動かすことです。入力コントロールを一切使わずに固定値を書いて、それだけで動作するか確かめます。

Patch(
    Employees,
    Defaults(Employees),
    {
        Title: "テスト太郎"
    }
)

ボタンのOnSelectにこれを貼り付け、Altキーを押しながらクリックすると1秒以内にSharePointへレコードが作成されます。うまく動いたら、次の列を1本ずつ追加していくやり方が、エラー発生時に原因を特定しやすくておすすめです。

私が社内で教えるときも、まずこのハードコードバージョンを試してもらいます。最初から入力フォームを組み込もうとして型エラーで詰まる人が多いので、まず動かすことを最優先にする順番が大切です。Power Appsは動いている状態から拡張していくほうが圧倒的に学びやすいです。列を1本追加して動かす、また1本追加して動かすという地道な繰り返しが、結果的に最短ルートになります。

列型別：値の渡し方

Patch関数で詰まる原因のほぼすべては、列の型に合わない値を渡していることです。Power Appsは型に対してとても厳格で、テキストを欲しがっているのに数値を渡すとすぐにエラーになります。「Power Appsはとにかく欲しいものだけを渡せ」という原則を念頭に置いて読み進めてください。

テキスト列

テキスト列には文字列を渡します。ハードコードならダブルクォートで囲み、入力コントロールを使うなら .Text プロパティを指定します。

// ハードコード
Title: "テスト太郎"

// TextInputから渡す場合
FirstName: inpFN.Text

TextInputコントロールのデフォルト出力は常に文字列です。テキスト列に渡すぶんには .Text をつけるだけでOKです。このあたりが数値列との大きな違いになりますので、次を読み進めてください。

数値列

数値列にはダブルクォートを外して数値をそのまま渡します。

Age: 28

TextInputから値を渡したいときは Value() 関数でラップしてください。これが最初の壁になる人がとても多いです。TextInputの .Text はどんな数字を打っても文字列として返します。28 と入力しても Power Apps からみれば「28という文字列」です。数値列は数値が欲しいので Value() で変換する必要があります。

Age: Value(inpAge.Text)

Value() を忘れると「Expected Number, found type Text」というエラーが出ます。次のセクションで詳しく取り上げますが、このエラーを見たらまず Value() が抜けていないか確認してください。

日付列

日付列にはDatePickerコントロールの .SelectedDate プロパティを使うのが定番です。.SelectedDate は日付型を返すので、そのまま渡せます。

// DatePickerから渡す場合
HireDate: dpHire.SelectedDate

// 今日の日付をハードコードする場合
HireDate: Today()

テスト段階では Today() を使ってハードコードしておくと、DatePickerの設定まで手が回らないうちでも動作確認ができて便利です。まずハードコードで動かして、後からコントロールに切り替える流れがおすすめです。

Yes/No列（SharePoint）

Yes/No列（SharePoint）には true または false をそのまま渡します。ダブルクォートは不要なBoolean値です。Toggleコントロールなら .Value プロパティがBoolean型を返すので、そのまま使えます。

// Toggleコントロールから渡す場合
GoodAtJob: tglGood.Value

// ハードコードの場合
GoodAtJob: false

なおDataverseのYes/No列はSharePointとは動作が異なります。DataverseのYes/No列はChoice型と同じ扱いになるため、true/falseをそのまま渡してもエラーになります。DataverseとのPatchについては別記事で解説しています。

よくあるエラーと対処法

Expected Number, found type Text

数値列にテキストを渡しているときに出るエラーです。原因はほぼ例外なく Value() の付け忘れです。数式バーでエラーが出ている箇所をホバーすると「The type of argument does not match the expected type: Number. Found type: Text.」という説明が表示されます。Numberが欲しいのにTextを渡したという意味なので、Value(inpAge.Text) のように Value() でラップして解決します。

体感的にいって、Value()の付け忘れはPatch関数デビュー時の詰まりポイント1位です。エラーメッセージをホバーして読む癖をつけると、原因が一発でわかるようになります。Power Appsが型を丁寧に教えてくれているので、それを読む習慣が身につくと一気に上達します。

TextInput全体を渡したときのエラー

.Text や .Value まで指定せず、コントロール名だけを渡すとエラーになります。Power Appsはコントロールオブジェクト全体を送ろうとするため、SharePointが受け取れないデータになってしまいます。

// NG（.Textが抜けている）
FirstName: inpFN

// OK
FirstName: inpFN.Text

ホバーして「Data type: Control」と表示されたら、プロパティまで掘り下げられていないサインです。ドットを追加して .Text や .SelectedDate などに辿り着くまで確認してください。コントロールのどのプロパティを使えばいいかわからないときも、ドットを打って補完候補を眺めると目的のプロパティが見つかります。

Format Textで整形する習慣

列が増えると、Patch関数を1行に書き連ねてしまいがちです。数式バー右下のFormat Textボタンで整形すると、列ごとに自動で改行されます。

Patch(
    Employees,
    Defaults(Employees),
    {
        Title: "テスト太郎",
        FirstName: inpFN.Text,
        Age: Value(inpAge.Text),
        HireDate: dpHire.SelectedDate,
        GoodAtJob: tglGood.Value
    }
)

列が5本・10本と増えても修正しやすく、どの列に何を渡しているか一目でわかります。Patch関数を書いたら必ずFormat Textをかけることをおすすめします。これは地味な習慣ですが、後から別の人が読むときにも助かりますし、自分が数週間後に見直すときにも理解しやすくなります。

変数と組み合わせた複雑なパターンが増えてきたときは、グローバル変数とコンテキスト変数の使い分けも参考にしてみてください。Patch関数と変数の組み合わせはアプリ設計の基本パターンになります。

まとめ

Patch関数の新規レコード作成は、Defaults・型に合わせた値渡し・Format Textの3点を押さえれば動かせます。Patch関数の基礎記事で全体像を把握した上で、この記事で列型別の渡し方を練習するのが自然な順番です。

次のステップは既存レコードの更新です。Defaultsを選択中のレコードに変えるだけで更新モードに切り替わります。Gallery.SelectedやvarRecordを使った更新パターンは既存レコード更新編で詳しく解説しています。

新規作成をはじめ、更新・下書き保存・複雑な列型など、Patch関数の応用パターンを体系的にまとめたPatch関数 応用ガイドも合わせて参照してください。

Patch関数は最初は難しく感じますが、使い込むほど手に馴染みます。市民開発は地道な積み重ねですが、Patchを使いこなせるようになると作れるアプリの幅が一気に広がります。楽しみながら進めていきましょう。

この記事を書いた人
守屋 祐輔
守屋 祐輔
物流会社の非エンジニアサラリーマン。Power Platformを独学で学び、営業職からDX担当に職務変更し、社内ツールを作っています。個人事業のデザイン業務にもPower Platformを活用し、市民開発.comの運営者として、アプリ開発やDX推進の経験を発信中。

Xでフォローしよう