Patch Fungsi

Terpakai kepada: Apl kanvas Aliran Desktop Copilot Studio Apl dipacu model Power Platform CLI Fungsi Dataverse

Ubah suai atau cipta satu atau lebih rekod dalam sumber data, atau cantum rekod di luar sumber data.

Gunakan fungsi untuk Patch mengubah suai rekod dalam situasi yang kompleks, seperti apabila anda melakukan kemas kini yang tidak memerlukan interaksi pengguna atau menggunakan borang yang merangkumi berbilang skrin.

Untuk mengemas kini dalam sumber data dengan lebih mudah bagi perubahan yang mudah, gunakan kawalan Borang edit sebaliknya. Apabila anda menambah kawalan Borang edit, anda menyediakan pengguna dengan borang untuk diisi dan kemudian menyimpan perubahan ke sumber data. Untuk maklumat lanjut, lihat Memahami borang data.

Tonton video ini untuk mengetahui cara menggunakan fungsi ini Patch :

Overview

Gunakan fungsi untuk Patch mengubah suai satu atau lebih rekod sumber data. Ia mengemas kini nilai medan tertentu tanpa menjejaskan sifat lain. Contohnya, formula ini mengubah nombor telefon pelanggan bernama Contoso:

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

Gunakan Patch dengan fungsi Lalai untuk mencipta rekod. Gunakan tingkah laku ini untuk membina skrin tunggal bagi kedua-dua mencipta dan mengedit rekod. Contohnya, formula ini mencipta rekod bagi pelanggan bernama Contoso:

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

Note

Apabila anda menampal koleksi dengan menggunakan rekod daripada sumber data dengan nilai lalai, operasi tampalan mengemas kini koleksi dengan kedua-dua nilai tampalan yang ditentukan dan nilai lalai daripada sumber data. DataSource bagi pernyataan tampalan dan DataSource fungsi Lalai mesti sepadan untuk mencipta rekod baharu.

Walaupun anda tidak bekerja dengan sumber data, anda boleh menggunakan Patch untuk menggabungkan dua atau lebih rekod. Contohnya, formula ini mencantumkan dua rekod ke dalam satu yang mengenal pasti kedua-dua nombor telefon dan lokasi untuk Contoso:

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

Description

Ubah suai atau cipta rekod dalam sumber data

Untuk menggunakan fungsi ini dengan sumber data, tentukan sumber data, dan kemudian tentukan rekod asas:

• Untuk mengubah suai rekod, rekod asas perlu datang daripada sumber data. Anda mungkin mendapatkan rekod asas melalui sifat Item galeri, meletakkannya dalam pembolehubah konteks atau mendapatkannya melalui laluan lain. Tetapi, anda mesti boleh mengesan rekod asas kembali ke sumber data. Keperluan ini penting kerana rekod termasuk maklumat tambahan yang membantu anda mencari rekod semula untuk pengubahsuaian.
• Untuk mencipta rekod, gunakan fungsi Defaults untuk mencipta rekod asas dengan nilai lalai.

Kemudian tentukan satu atau lebih rekod yang berubah, setiap satu mengandungi nilai sifat baharu yang menggantikan nilai sifat dalam rekod asas. Rekod yang berubah diproses dalam susunan daripada permulaan senarai argumen ke akhir, dengan nilai sifat terkini menggantikan yang sebelumnya.

Nilai pulangan ialah Patch rekod yang anda ubah suai atau cipta. Jika anda mencipta rekod, nilai pulangan mungkin termasuk sifat yang dijana oleh sumber data secara automatik. Walau bagaimanapun, nilai pulangan tidak menyediakan nilai untuk medan jadual yang berkaitan.

Contohnya, anda menggunakan Set(MyAccount, Patch(Accounts, First(Account), 'Account Name': "Example name")); dan kemudian MyAccount.'Primary Contact'.'Full Name'. Anda tidak boleh menghasilkan nama penuh dalam kes ini. Sebaliknya, untuk mengakses medan jadual berkaitan, gunakan carian berasingan seperti:

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

Apabila anda mengemas kini sumber data, satu atau lebih isu mungkin timbul. Gunakan IfError dan IsError dengan nilai pulangan daripada Patch untuk mengesan dan bertindak balas terhadap ralat, seperti yang diterangkan oleh Pengendalian Ralat . Anda boleh juga menggunakan fungsi Ralat untuk mengenal pasti dan memeriksa isu, seperti yang Bekerja dengan Sumber Data terangkan.

Fungsi berkaitan termasuk fungsi Update untuk menggantikan keseluruhan rekod, dan fungsi Collect untuk mencipta rekod. Gunakan fungsi UpdateIf untuk mengubah suai sifat tertentu bagi berbilang rekod berasaskan pada syarat.

Ubah suai atau cipta set rekod dalam data sumber

Anda juga boleh menggunakan Patch untuk mencipta atau mengubah suai berbilang rekod dengan satu panggilan.

Daripada lulus satu rekod asas, sediakan jadual rekod asas dalam hujah kedua. Sediakan rekod perubahan dalam jadual juga, sepadan satu demi satu dengan rekod asas. Bilangan rekod dalam setiap jadual ubah mesti sama dengan bilangan rekod dalam jadual asas.

Apabila anda menggunakan Patch dengan cara ini, nilai pulangan juga merupakan jadual dengan setiap rekod sepadan satu untuk satu dengan rekod asas dan perubahan.

Cantumkan rekod di luar sumber data

Tentukan dua atau lebih rekod yang anda mahu cantumkan. Fungsi memproses rekod dalam susunan dari permulaan senarai hujah hingga akhir, dengan nilai sifat kemudian mengatasi nilai terdahulu.

Patch mengembalikan rekod yang digabungkan dan tidak mengubah suai argumen atau rekodnya dalam mana-mana sumber data.

Syntax

Ubah suai atau cipta rekod dalam sumber data

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

• Sumber Data– Diperlukan. Sumber data yang mengandungi rekod yang anda mahu ubah suai atau akan mengandungi rekod yang anda mahu cipta.
• BaseRecord – Diperlukan. Rekod untuk diubah suai atau cipta. Jika rekod datang daripada sumber data, fungsi mencari dan mengubah suai rekod. Jika hasil Lalai digunakan, fungsi mencipta rekod. DataSource pernyataan tampalan dan DataSource fungsi Lalai mesti sepadan untuk mencipta rekod baharu.
• ChangeRecords – Diperlukan. Satu atau lebih rekod yang mengandungi sifat untuk diubah suai dalam BaseRecord. Fungsi ini memproses rekod perubahan mengikut urutan dari permulaan senarai hujah hingga akhir, dengan nilai sifat kemudian mengatasi yang terdahulu.

Ubah suai atau cipta set rekod dalam data sumber

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

• Sumber Data– Diperlukan. Sumber data mengandungi rekod yang anda mahu ubah suai atau akan mengandungi rekod yang anda mahu cipta.
• BaseRecordTable – Diperlukan. Jadual rekod untuk diubah suai atau dicipta. Jika rekod datang daripada sumber data, fungsi mencari dan mengubah suai rekod. Jika hasil Lalai digunakan, fungsi mencipta rekod. DataSource pernyataan tampalan dan DataSource fungsi Lalai mesti sepadan untuk mencipta rekod baharu.
• ChangeRecordTables – Diperlukan. Satu atau lebih jadual rekod yang mengandungi sifat untuk diubah suai bagi setiap rekod BaseRecordTable. Fungsi ini memproses rekod perubahan mengikut urutan dari permulaan senarai hujah hingga akhir, dengan nilai sifat kemudian mengatasi yang terdahulu.

Merge records

Patch( Rekod1, Rekod2 [, ...] )

• Rekod - Diperlukan. Sekurang-kurangnya dua rekod yang anda mahu cantumkan. Fungsi ini memproses rekod mengikut urutan dari permulaan senarai hujah hingga akhir, dengan nilai sifat kemudian mengatasi nilai terdahulu.

Examples

Ubah suai atau cipta rekod (dalam sumber data)

Dalam contoh ini, anda mengubah suai atau mencipta rekod dalam sumber data bernama Aiskrim. Sumber data mengandungi data dalam jadual ini dan secara automatik menjana nilai dalam lajurID:

Untuk mencipta versi dalam memori sumber data ini supaya anda boleh mencuba contoh ini, nilai formula ini:

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

Formula	Description	Result
Patch( Ais Krim, Cari( IceCream, Perisa = "Coklat" ), { Kuantiti: 400 } )	Mengubah suai rekod dalam sumber data IceCream: Lajur ID rekod untuk diubah suai mengandungi nilai 1. (Rekod Coklat mempunyai ID itu.) Nilai dalam lajur kuantiti berubah ke 400.	{ ID: 1, Perisa: "Coklat", Kuantiti: 400 } Entri Coklat dalam sumber data Ais Krim diubah suai.
Patch( Aiskrim, Lalai( Ais Krim ), { Perisa: "Strawberi" } )	Cipta rekod dalam sumber data IceCream: Lajur ID mengandungi nilai 3, di mana sumber data dijana secara automatik. Lajur Kuantiti mengandungi 0, yang merupakan nilai lalai untuk lajur dalam sumber data IceCream, yang menentukan fungsi Defaults. Lajur Perasa mengandungi nilai Strawberi.	{ ID: 3, Perisa: "Strawberi", Kuantiti: 0 } Entri Strawberi dalam sumber data Ais Krim dicipta.

Selepas formula sebelumnya dinilai, sumber data berakhir dengan nilai ini:

Cantum rekod (di luar sumber data)

Formula	Description	Result
Patch( { Nama: "James", Skor: 90 }, { Nama: "Jim", Lulus: benar } )	Cantumkan dua rekod di luar sumber data: Nilai dalam lajur Nama untuk setiap rekod tidak sepadan. Hasil mengandungi nilai (Jim) dalam rekod yang lebih dekat dengan senarai argumen berbanding nilai (James) dalam rekod yang lebih dekat dengan awal. Rekod pertama mengandungi lajur (Skor) yang tidak wujud dalam rekod kedua. Hasil mengandungi lajur dengan nilai (90). Rekod kedua mengandungi lajur (Lulus) yang tidak wujud dalam rekod pertama. Hasil mengandungi lajur dengan nilai (benar).	{ Nama: "Jim", Skor: 90, Lulus: benar }

Ubah suai atau cipta satu set rekod (dalam sumber data)

Apabila anda menggunakan Patch dengan jadual dan bukannya rekod tunggal, anda boleh mencipta atau mengubah suai berbilang rekod dalam satu panggilan. Nilai pulangan ialah jadual rekod yang sepadan dengan satu demi satu dengan jadual input.

Contoh ini mengemas kini Kuantiti untuk berbilang perisa dalam sumber data Aiskrim sekaligus:

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

Hasilnya ialah jadual dengan rekod yang dikemas kini: { ID: 1, Flavor: "Chocolate", Quantity: 300 } dan { ID: 2, Flavor: "Vanilla", Quantity: 400 }.

Contoh ini mencipta berbilang rekod baharu menggunakan Lalai:

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

Note

Apabila anda menggunakan Patch dengan jadual, bilangan rekod dalam setiap jadual perubahan mesti sepadan dengan bilangan rekod dalam jadual asas. Jika tidak, ralat berlaku.

Untuk mengesan ralat apabila anda mengubah suai berbilang rekod, gunakan IfError. IfError ialah mekanisme pilihan dan berfungsi merentas hos Power Fx:

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

Patch dengan jenis lajur Dataverse

Contoh berikut digunakan secara khusus untuk sumber data Microsoft Dataverse. Bentuk rekod berbeza mengikut sumber data (contohnya, SharePoint dan SQL Server mempunyai format yang berbeza).

Lajur pilihan: Untuk mengesetkan lajur Pilihan, gunakan nilai enum secara langsung. Contoh ini menetapkan lajur pilihan Status pada jadual Akaun :

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

Lajur carian: Untuk mengesetkan lajur Carian, sediakan rekod dengan kunci utama jadual yang berkaitan. Contoh ini menetapkan carian Kenalan Utama pada rekod Akaun :

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

Note

Contoh jenis lajur ini adalah khusus Dataverse. Sumber data lain, seperti SharePoint atau SQL Server, mungkin memerlukan bentuk rekod yang berbeza untuk jenis lajur yang serupa. Rujuk dokumentasi untuk sumber data khusus anda untuk format yang betul.

Perwakilan dalam formula yang menggunakan Patch

Fungsi itu Patch sendiri tidak tertakluk kepada perwakilan kerana ia menulis kepada sumber data dan bukannya menanyakannya. Walau bagaimanapun, amaran perwakilan mungkin muncul dalam formula yang menggunakan Patch jika bahagian pemilihan rekod formula (seperti Penapis, Carian atau ForAll) melibatkan pertanyaan yang melebihi had perwakilan sumber data.

Apabila anda melihat amaran perwakilan dalam formula yang termasuk Patch, semak sama ada amaran digunakan pada fungsi pengambilan data dan bukannya kepada Patch dirinya sendiri. Untuk maklumat lanjut tentang perwakilan, lihat Memahami perwakilan dalam aplikasi kanvas.

Ralat biasa dengan Patch fungsi

Apabila anda menggunakan Patch fungsi, ralat mungkin berlaku disebabkan sambungan sumber data, keizinan atau konflik data. Gunakan IfError dan IsError untuk mengesan ralat dan bertindak balas dengan sewajarnya.

• "Ralat rangkaian apabila menggunakan Patch fungsi": Ralat ini biasanya menunjukkan bahawa apl tidak dapat mencapai sumber data. Punca biasa termasuk sambungan internet terputus, sumber data tidak tersedia buat sementara waktu atau kebenaran yang tidak mencukupi untuk pengguna semasa. Balutkan Patch panggilan dalam IfError untuk memberikan mesej yang bermakna kepada pengguna.

• "Konflik wujud dengan perubahan pada pelayan": Ralat ini berlaku apabila pengguna atau proses lain mengubah suai rekod yang sama antara masa apl anda membaca rekod dan menulis perubahan. Muat semula sumber data dengan memanggil fungsi Muat Semula dan cuba semula operasi.

• Ralat keizinan: Jika pengguna tidak mempunyai keizinan untuk mencipta atau mengubah suai rekod dalam sumber data, panggilan gagal Patch . Gunakan IfError untuk menangkap ralat berkaitan kebenaran dan membimbing pengguna.

Untuk corak pengendalian ralat umum, lihat Pengendalian ralat.

Penggunaan Sebagai atau RekodIni

Gunakan kata kunci As atau ThisRecord dalam formula anda untuk mengelakkan konteks penilaian yang samar-samar.

Dalam contoh berikut, pertimbangkan yang pertama Lookup dalam If kenyataan. (OrderID = A[@OrderID]) dijangka membandingkan OrderId dalam Lookup skop dengan OrderId koleksi A dalam ForAll skop. Dalam kes ini, anda mungkin mahu A[@OrderId] menyelesaikannya sebagai parameter tempatan. Tetapi ia samar-samar.

Power Apps pada masa ini mentafsirkan kedua-dua bahagian kiri OrderId dan sebelah kanan A[@OrderId] sebagai medan dalam skop Lookup. Oleh itu, Lookup sentiasa mencari baris pertama kerana [dbo].[Orders1] keadaan sentiasa benar (iaitu, mana-mana OrderId baris adalah 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"
       }
   )
    )
)

Menggunakan Sebagai atau RekodIni

Apabila boleh, gunakan pengendali Sebagai atau kata kunci ThisRecord untuk menyahkekaburan sebelah kiri. Seperti yang disyorkan untuk senario sebelumnya.

Apabila formula anda menggunakan berbilang skop dengan ForAll, Filter, dan Lookup pada sumber data atau jadual yang sama, parameter skop mungkin bertembung dengan medan yang sama di tempat lain. Oleh itu, gunakan pengendali Sebagai atau ThisRecord untuk menyelesaikan nama medan dan mengelakkan kekaburan.

Sebagai contoh, anda boleh menggunakan pengendali Sebagai untuk menyahkekaburan 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"
       }
   )
    )
)

Sebagai alternatif, anda boleh menggunakan RekodIni 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 mengetahui lebih lanjut tentang penggunaan pengendali Sebagai dan ThisRecord, lihat artikel Pengendali .