fungsi Patch

Berlaku untuk: Aplikasi Canvas Copilot Studio Desktop mengalir aplikasi berbasis model Fungsi Power Platform CLI Dataverse

Mengubah atau membuat satu atau beberapa rekaman di sumber data, atau menggabungkan rekaman di luar sumber data.

Patch Gunakan fungsi untuk memodifikasi rekaman dalam situasi kompleks, seperti saat Anda melakukan pembaruan yang tidak memerlukan interaksi pengguna atau menggunakan formulir yang mencakup beberapa layar.

Untuk memperbarui rekaman di sumber data secara lebih mudah untuk perubahan sederhana, gunakan kontrol Edit formulir sebagai gantinya. Bila anda menambahkan kontrol Edit formulir, Anda menyediakan formulir untuk diisi dan kemudian menyimpan perubahan ke sumber data kepada pengguna. Untuk informasi lebih lanjut, lihat Memahami formulir data.

Tonton video ini untuk mempelajari cara menggunakan Patch fungsi:

Overview

Patch Gunakan fungsi untuk mengubah satu atau beberapa rekaman sumber data. Ini memperbarui nilai bidang tertentu tanpa memengaruhi properti lain. Misalnya, rumus ini mengubah nomor telepon untuk pelanggan bernama Contoso:

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

Gunakan Patch dengan fungsi Default untuk membuat rekaman. Gunakan perilaku ini untuk membuat satu layar untuk pembuatan dan pengeditan rekaman. Misalnya, rumus ini membuat rekaman untuk pelanggan bernama Contoso:

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

Note

Saat Anda menambal koleksi dengan menggunakan rekaman dari sumber data dengan nilai default, operasi patch memperbarui koleksi dengan nilai patch yang ditentukan dan nilai default dari sumber data. DataSource dari pernyataan patch dan DataSource dari fungsi Defaults harus cocok untuk membuat rekaman baru.

Bahkan jika Anda tidak bekerja dengan sumber data, Anda bisa menggunakan Patch untuk menggabungkan dua rekaman atau lebih. Contohnya, rumus ini menggabungkan dua rekaman menjadi satu yang mengidentifikasi nomor telepon dan lokasi Contoso:

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

Description

Mengubah dan membuat rekaman di sumber data

Untuk menggunakan fungsi ini dengan sumber data, tentukan sumber data, lalu tentukan rekaman dasar:

• Untuk memodifikasi rekaman, rekaman dasar harus berasal dari sumber data. Anda mungkin mendapatkan rekaman dasar melalui properti Items galeri, menempatkannya dalam variabel konteks, atau mendapatkannya melalui jalur lain. Namun, Anda harus dapat melacak catatan dasar kembali ke sumber data. Persyaratan ini penting karena catatan menyertakan informasi tambahan yang membantu Anda menemukan catatan kembali untuk dimodifikasi.
• Untuk membuat rekaman, gunakan fungsi Defaults untuk membuat rekaman dasar dengan nilai default.

Kemudian tentukan satu atau beberapa rekaman yang diubah, yang masing-masing berisi nilai properti baru yang menimpa nilai properti dalam rekaman dasar. Rekaman perubahan diproses secara berurutan dari awal daftar argumen sampai akhir, dengan nilai properti yang lebih baru menimpa yang sebelumnya.

Nilai yang dikembalikan adalah Patch rekaman yang Anda ubah atau buat. Jika Anda membuat rekaman, nilai pengembalian mungkin menyertakan properti yang dihasilkan sumber data secara otomatis. Namun, nilai hasil tidak memberikan nilai untuk bidang tabel terkait.

Misalnya, Anda menggunakan Set(MyAccount, Patch(Accounts, First(Account), 'Account Name': "Example name")); dan kemudian MyAccount.'Primary Contact'.'Full Name'. Anda tidak dapat menghasilkan nama lengkap dalam kasus ini. Justru, untuk mengakses bidang tabel terkait, gunakan pencarian terpisah seperti:

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

Saat Anda memperbarui sumber data, satu atau beberapa masalah mungkin muncul. Gunakan IfError dan IsError dengan nilai pengembalian dari Patch untuk mendeteksi dan merespons kesalahan, seperti yang dijelaskan oleh Penanganan Kesalahan . Anda juga dapat menggunakan fungsi Errors untuk mengidentifikasi dan memeriksa masalah, seperti yang dijelaskan Bekerja dengan Sumber Data.

Fungsi terkait mencakup fungsi Update untuk menggantikan seluruh rekaman, dan fungsi Collect untuk membuat rekaman. Gunakan fungsi UpdateIf untuk memodifikasi properti tertentu dari beberapa rekaman berdasarkan kondisi.

Mengubah dan membuat rangkaian rekaman dalam sumber data

Anda juga dapat menggunakan Patch untuk membuat atau memodifikasi beberapa rekaman dengan satu panggilan.

Alih-alih meneruskan satu rekaman dasar, berikan tabel rekaman dasar di argumen kedua. Berikan catatan perubahan dalam tabel juga, sesuai satu demi satu dengan catatan dasar. Jumlah rekaman di setiap tabel perubahan harus sama dengan jumlah rekaman di tabel dasar.

Saat Anda menggunakan Patch dengan cara ini, nilai yang ditampilkan juga merupakan tabel dengan setiap rekaman yang sesuai satu-untuk-satu dengan catatan dasar dan perubahan.

Menggabungkan rekaman di luar sumber data

Tentukan dua rekaman atau lebih yang ingin Anda gabungkan. Fungsi ini memproses rekaman dalam urutan dari awal daftar argumen hingga akhir, dengan nilai properti selanjutnya menggantikan yang sebelumnya.

Patch mengembalikan rekaman gabungan dan tidak mengubah argumen atau rekamannya di sumber data apa pun.

Syntax

Mengubah dan membuat rekaman di sumber data

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

• Sumber Data– Wajib. Sumber data yang berisi rekaman yang akan dimodifikasi atau berisi rekaman yang ingin Anda buat.
• BaseRecord – Wajib. Rekaman untuk dimodifikasi atau dibuat. Jika rekaman berasal dari sumber data, fungsi menemukan dan memodifikasi rekaman. Jika hasil Default digunakan, fungsi akan membuat rekaman. Sumber Data pernyataan patch dan Sumber Data fungsi Default harus cocok untuk membuat rekaman baru.
• ChangeRecords – Wajib. Satu atau beberapa rekaman yang berisi properti untuk dimodifikasi di BaseRecord. Fungsi ini memproses catatan perubahan secara berurutan dari awal daftar argumen hingga akhir, dengan nilai properti selanjutnya menggantikan yang sebelumnya.

Mengubah dan membuat rangkaian rekaman dalam sumber data

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

• Sumber Data– Wajib. Sumber data yang berisi rekaman yang akan dimodifikasi atau berisi rekaman yang ingin Anda buat.
• BaseRecordTable – Wajib. Tabel rekaman untuk dimodifikasi atau dibuat. Jika rekaman berasal dari sumber data, fungsi menemukan dan memodifikasi rekaman. Jika hasil Default digunakan, fungsi akan membuat rekaman. Sumber Data pernyataan patch dan Sumber Data fungsi Default harus cocok untuk membuat rekaman baru.
• ChangeRecordTables – Wajib. Satu atau beberapa tabel rekaman yang berisi properti untuk diubah untuk setiap rekaman dari BaseRecordTable. Fungsi ini memproses catatan perubahan secara berurutan dari awal daftar argumen hingga akhir, dengan nilai properti selanjutnya menggantikan yang sebelumnya.

Merge records

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

• Catatan - Wajib. Sedikitnya dua rekaman yang ingin digabungkan. Fungsi ini memproses catatan secara berurutan dari awal daftar argumen hingga akhir, dengan nilai properti selanjutnya menggantikan yang sebelumnya.

Examples

Mengubah dan membuat rekaman (di sumber data)

Dalam contoh ini, Anda memodifikasi atau membuat rekaman di sumber data bernama IceCream. Sumber data berisi data dalam tabel ini dan secara otomatis menghasilkan nilai di kolomID:

Untuk membuat versi dalam memori dari sumber data ini sehingga Anda dapat mencoba contoh ini, evaluasi rumus ini:

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

Formula	Description	Result
Patch(IceCream, LookUp( IceCream, Rasa = "Cokelat" ), { Jumlah: 400 } )	Memodifikasi rekaman di sumber data IceCream: Kolom ID rekaman untuk dimodifikasi berisi nilai 1. (Rekaman Rekaman memiliki ID tersebut.) Nilai dalam kolom Quantity berubah menjadi 400.	{ ID: 1, Rasa: "Cokelat", jumlah: 400 } Entri Cokelat di sumber data IceCream diubah.
Patch( Es Krim, Default ( Es Krim ), { Rasa: "Stroberi" } )	Membuat rekaman di sumber data IceCream: Kolom ID berisi nilai 3, dengan sumber data menghasilkan secara otomatis. Kolom Quantity berisi 0, yang merupakan nilai default untuk kolom tersebut dalam sumber data IceCream data, seperti yang ditentukan fungsi Defaults. Kolom Flavor berisi nilai Strawberry.	{ ID: 3, Rasa: "Stroberi", Kuantitas: 0 } Entri Stroberi di sumber data IceCream dibuat.

Setelah rumus sebelumnya dievaluasi, sumber data diakhiri dengan nilai-nilai berikut:

Menggabungkan rekaman (di luar sumber data)

Formula	Description	Result
Patch( { Nama: "James", Skor: 90 }, { Nama: "Jim", Lulus: benar } )	Menggabungkan dua rekaman di luar sumber data: Nilai pada kolom Name untuk setiap rekaman tidak sesuai. Hasil berisi nilai (Jim) di rekaman yang lebih dekat ke akhir daftar argumen, bukan nilai (James) di rekaman yang lebih dekat dengan awal. Rekaman pertama berisi kolom (Score) yang tidak ada di rekaman kedua. Hasilnya berisi kolom tersebut dengan nilainya (90). Rekaman kedua berisi kolom (Passed) yang tidak ada di rekaman pertama. Hasilnya berisi kolom tersebut dengan nilainya (true).	{ Nama: "Jim", Skor: 90, Lulus: benar }

Memodifikasi atau membuat sekumpulan rekaman (dalam sumber data)

Saat Anda menggunakan Patch dengan tabel, bukan rekaman tunggal, Anda dapat membuat atau memodifikasi beberapa rekaman dalam satu panggilan. Nilai yang dikembalikan adalah tabel rekaman yang sesuai satu-untuk-satu dengan tabel input.

Contoh ini memperbarui Kuantitas untuk beberapa ragam di sumber data IceCream sekaligus:

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

Hasilnya adalah tabel dengan catatan yang diperbarui: { ID: 1, Flavor: "Chocolate", Quantity: 300 } dan { ID: 2, Flavor: "Vanilla", Quantity: 400 }.

Contoh ini membuat beberapa rekaman baru menggunakan Default:

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

Note

Saat Anda menggunakan Patch dengan tabel, jumlah rekaman dalam setiap tabel perubahan harus cocok dengan jumlah rekaman dalam tabel dasar. Jika tidak, kesalahan terjadi.

Untuk mendeteksi kesalahan saat Anda mengubah beberapa rekaman, gunakan IfError. IfError adalah mekanisme yang disukai dan berfungsi di seluruh host Power Fx:

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

Patch dengan jenis kolom Dataverse

Contoh berikut berlaku secara khusus untuk sumber data Microsoft Dataverse. Bentuk rekaman bervariasi menurut sumber data (misalnya, SharePoint dan SQL Server memiliki format yang berbeda).

Kolom pilihan: Untuk mengatur kolom Pilihan, gunakan nilai enum secara langsung. Contoh ini menetapkan kolom pilihan Status pada tabel Akun :

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

Kolom pencarian: Untuk mengatur kolom Pencarian, berikan rekaman dengan kunci utama tabel terkait. Contoh ini menetapkan pencarian Kontak Utama pada rekaman Akun :

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

Note

Contoh jenis kolom ini bersifat khusus Dataverse. Sumber data lain, seperti SharePoint atau SQL Server, mungkin memerlukan bentuk rekaman yang berbeda untuk jenis kolom yang serupa. Lihat dokumentasi untuk sumber data spesifik Anda untuk format yang benar.

Delegasi dalam rumus yang menggunakan Patch

Fungsi itu Patch sendiri tidak tunduk pada delegasi karena menulis ke sumber data daripada mengkuerinya. Namun, peringatan delegasi mungkin muncul dalam rumus yang digunakan Patch jika bagian pemilihan rekaman dari rumus (seperti Filter, Pencarian, atau ForAll) melibatkan kueri yang melebihi batas delegasi sumber data.

Saat Anda melihat peringatan delegasi dalam rumus yang menyertakan Patch, periksa apakah peringatan berlaku untuk fungsi pengambilan data, bukan untuk Patch dirinya sendiri. Untuk informasi selengkapnya tentang delegasi, lihat Memahami delegasi di aplikasi kanvas.

Kesalahan umum dengan Patch fungsi

Saat Anda menggunakan fungsi ini Patch , kesalahan mungkin terjadi karena konektivitas sumber data, izin, atau konflik data. Gunakan IfError dan IsError untuk mendeteksi kesalahan dan merespons dengan tepat.

• "Error jaringan saat menggunakan Patch fungsi": Error ini biasanya menunjukkan bahwa aplikasi tidak dapat menjangkau sumber data. Penyebab umum termasuk koneksi internet terputus, sumber data tidak tersedia untuk sementara, atau izin yang tidak memadai untuk pengguna saat ini. Bungkus Patch panggilan di IfError untuk memberikan pesan yang bermakna kepada pengguna.

• "Ada konflik dengan perubahan di server": Error ini terjadi saat pengguna atau proses lain mengubah data yang sama antara saat aplikasi membaca data dan menulis perubahan. Segarkan sumber data dengan memanggil fungsi Refresh dan coba lagi operasi.

• Kesalahan izin: Jika pengguna tidak memiliki izin untuk membuat atau mengubah rekaman di sumber data, panggilan gagal Patch . Gunakan IfError untuk menangkap kesalahan terkait izin dan memandu pengguna.

Untuk pola penanganan kesalahan umum, lihat Penanganan kesalahan.

Penggunaan As atau thisrecord

Gunakan kata kunci As atau ThisRecord dalam rumus Anda untuk menghindari konteks evaluasi yang ambigu.

Dalam contoh berikut, pertimbangkan yang pertama Lookup dalam If pernyataan. (OrderID = A[@OrderID]) diharapkan untuk membandingkan dalam OrderIdLookup ruang lingkup dengan OrderId koleksi A dalam ForAll cakupan. Dalam hal ini, Anda mungkin ingin A[@OrderId] menyelesaikannya sebagai parameter lokal. Tapi itu ambigu.

Power Apps saat ini menafsirkan sisi kiri OrderId dan sisi kanan A[@OrderId] sebagai bidang dalam cakupan Lookup. Oleh karena itu, Lookup selalu menemukan baris pertama karena [dbo].[Orders1] kondisinya selalu benar (yaitu, baris OrderId apa pun sama dengan dirinya sendiri).

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

Penggunaan As atau thisrecord

Jika memungkinkan, gunakan operator As atau kata kunci ThisRecord untuk mendisambiguasi sisi kiri. Seperti yang direkomendasikan untuk skenario sebelumnya.

Saat rumus Anda menggunakan beberapa cakupan dengan ForAll, Filter, dan Lookup pada sumber data atau tabel yang sama, parameter cakupan mungkin bertabrakan dengan bidang yang sama di tempat lain. Oleh karena itu, gunakan operator As atau ThisRecord untuk menyelesaikan nama bidang dan menghindari ambiguitas.

Misalnya, Anda dapat menggunakan operator As untuk mendisambiguasi dalam contoh berikut.

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

Atau, Anda dapat menggunakan thisrecord untuk tujuan yang sama.

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

Untuk mempelajari selengkapnya tentang penggunaan operator As dan ThisRecord, lihat artikel Operator .