Patch פונקציה

חל על: אפליקציות Canvas Copilot Studio Desktop זורמות אפליקציות מונחות מודלים פונקציות Power Platform CLI Dataverse

משנה או יוצרת רשומה אחת או יותר במקור נתונים, או ממזגת רשומות מחוץ למקור נתונים.

השתמש בפונקציה Patch כדי לשנות רשומות במצבים מורכבים, כגון בעת ביצוע עדכונים שאינם דורשים אינטראקציה מצד המשתמש או שימוש בטפסים המשתרעים על פני מסכים מרובים.

כדי לעדכן רשומות במקור נתונים ביתר קלות עבור שינויים פשוטים, השתמש במקום זאת בפקד Edit form. כשאתה מוסיף פקד Edit form, אתה מספק למשתמשים טופס למלא ולאחר מכן שומר את השינויים במקור נתונים. לקבלת מידע נוסף, ראה הכרת טפסי נתונים.

צפה בסרטון וידאו זה כדי ללמוד כיצד להשתמש בפונקציה Patch :

Overview

השתמש בפונקציה Patch כדי לשנות רשומה אחת או יותר של מקור נתונים. הוא מעדכן את ערכי השדות הספציפיים מבלי להשפיע על תכונות אחרות. לדוגמה, נוסחה זו משנה את מספר הטלפון של לקוח בשם Contoso:

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

השתמש Patch עם הפונקציה Defaults כדי ליצור רשומות. השתמש באופן פעולה זה כדי לבנות מסך יחיד הן עבור יצירת רשומות והן עבור עריכת רשומות. לדוגמה, נוסחה זו יוצרת רשומה עבור לקוח בשם 'בר-אילן':

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

Note

כאשר אתה מתקן אוסף באמצעות רשומה ממקור נתונים עם ערכים ברירת מחדל, פעולת התיקון מעדכנת את האוסף גם עם ערכי התיקון שצוינו וגם עם ערכי ברירת המחדל ממקור הנתונים. DataSource של פקודת התיקון ו-DataSource של פונקציית Defaults חייבים להתאים כדי ליצור רשומה חדשה.

גם אם אינך עובד עם מקור נתונים, באפשרותך להשתמש בו כדי למזג Patch שתי רשומות או יותר. לדוגמה, נוסחה זו ממזגת שתי רשומות לרשומה אחת המזהה הן את מספר הטלפון והן את המיקום עבור 'בר-אילן':

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

Description

שינוי או יצירה של רשומה במקור נתונים

כדי להשתמש בפונקציה זו עם מקור נתונים, ציין את מקור הנתונים ולאחר מכן ציין רשומת בסיס:

• כדי לשנות רשומה, הרשומה הבסיסית צריכה להגיע ממקור נתונים. אתה יכול לקבל את רשומת הבסיס דרך תכונת הפריטים של גלריה, למקם אותה במשתנה הקשר, או לקבל אותה דרך נתיב אחר. אבל, עליך להיות מסוגל לעקוב אחרי רשומת הבסיס חזרה למקור הנתונים. דרישה זו חשובה כי הרשומה כוללת מידע נוסף שעוזר לך למצוא את הרשומה שוב לצורך שינוי.
• כדי ליצור רשומה, השתמש בפונקציה Defaults כדי ליצור רשומת בסיס עם ערכי ברירת מחדל.

לאחר מכן ציין רשומת שינוי אחת או יותר, שכל אחת בה מכילה ערכי מאפיינים חדשים שעוקפים ערכי מאפיינים ברשומת הבסיס. רשומות שינוי מעובדות לפי הסדר מתחילת רשימת הארגומנטים ועד לסוף, כאשר ערכי מאפיין מאוחרים יותר עוקפים ערכים מוקדמים יותר.

ערך ההחזרה 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'

בעת עדכון מקור נתונים, בעיה אחת או יותר עלולה להתעורר. השתמש ב- IfErrorוב- IsErrorPatch עם הערך המוחזר מ- כדי לזהות שגיאות ולהגיב לשגיאות, כפי שמתאר טיפול בשגיאות . אפשר גם להשתמש בפונקציה שגיאות כדי לזהות ולבחון בעיות, כפי שהסעיף עבודה עם מקורות נתונים מתאר.

פונקציות קשורות כוללות את הפונקציה Update להחלפת רשומה שלמה, ואת הפונקציה Collect ליצירת רשומה. השתמש בפונקציה UpdateIf כדי לשנות מאפיינים ספציפיים של רשומות מרובות בהתבסס על תנאי.

שינוי או יצירה של ערכת רשומות במקור נתונים

ניתן גם להשתמש Patch בו ליצירת או שינוי של מספר רשומות בשיחה אחת.

במקום להעביר רשומת בסיס אחת, יש לספק טבלה של רשומות בסיס באריגומנט השני. ספק גם רשומות שינוי בטבלה, תוך התאמה אחת לאחת עם רשומות הבסיס. מספר הרשומות בכל טבלת שינויים מוכרח להיות זהה למספר הרשומות בטבלת הבסיס.

כאשר משתמשים Patch בדרך זו, ערך ההחזרה הוא גם טבלה שבה כל רשומה מתאימה אחד לאחד לרשומות הבסיס ושינוי.

מיזוג רשומות מחוץ למקור נתונים

ציין שתי רשומות או יותר שברצונך למזג. הפונקציה מעבדת רשומות בסדר מתחילת רשימת הארגומנטים ועד סופה, כאשר ערכי תכונות מאוחרים יותר גוברים על ערכי הקודמים.

Patch מחזירה את הרשומה הממוזגת ולא משנה את הארגומנטים או הרשומות שלה במקורות נתונים כלשהם.

Syntax

שינוי או יצירה של רשומה במקור נתונים

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

• DataSource – נדרש. מקור הנתונים שמכיל את הרשומה שברצונך לשנות או שיכלול את הרשומה שברצונך ליצור.
• BaseRecord – חובה. הרשומה לשינוי או ליצירה. אם הרשומה הגיעה ממקור נתונים, הפונקציה מוצאת ומשנה את הרשומה. אם משתמשים בתוצאה של Defaults , הפונקציה יוצרת רשומה. DataSource של משפט התיקון ומקור הנתונים של הפונקציה Defaults חייבים להתאים כדי ליצור רשומה חדשה.
• ChangeRecords – חובה. רשומה אחת או יותר הכוללת מאפיינים לשינוי ב- BaseRecord. תהליכי הפונקציה משנים רשומות לפי הסדר מתחילת רשימת הארגומנטים ועד הסוף, כאשר ערכי תכונות מאוחרים יותר גוברים על ערכי הקודמים.

שינוי או יצירה של ערכת רשומות במקור נתונים

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

• DataSource – נדרש. מקור הנתונים שמכיל את הרשומות שברצונך לשנות או שיכלול את הרשומות שברצונך ליצור.
• BaseRecordTable – נדרש. טבלת רשומות לשינוי או ליצירה. אם הרשומה הגיעה ממקור נתונים, הפונקציה מוצאת ומשנה את הרשומה. אם משתמשים בתוצאה של Defaults , הפונקציה יוצרת רשומה. DataSource של משפט התיקון ומקור הנתונים של הפונקציה Defaults חייבים להתאים כדי ליצור רשומה חדשה.
• ChangeRecordTables – נדרש. טבלת רשומות אחת או יותר המכילות מאפיינים לשינוי עבור כל רשומה של BaseRecordTable. תהליכי הפונקציה משנים רשומות לפי הסדר מתחילת רשימת הארגומנטים ועד הסוף, כאשר ערכי תכונות מאוחרים יותר גוברים על ערכי הקודמים.

Merge records

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

• רשומות - חובה. לפחות שתי רשומות שברצונך למזג. הפונקציה מעבדת רשומות לפי סדר מתחילת רשימת הארגומנטים ועד סופה, כאשר ערכי תכונות מאוחרים יותר גוברים על ערכי הקודמים.

Examples

שינוי או יצירה של רשומה (במקור נתונים)

בדוגמאות אלו, אתה משנה או יוצר רשומה במקור נתונים בשם IceCream. מקור הנתונים מכיל את הנתונים בטבלה זו ומייצר אוטומטית את הערכים בעמודתהמזהה:

כדי ליצור גרסה בזיכרון של מקור הנתונים הזה כדי שתוכלו לנסות את הדוגמאות הבאות, העריכו את הנוסחה הזו:

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

Formula	Description	Result
Patch(קרח, LookUp ( גלידה, טעם = "שוקולד"), { כמות: 400 } )	שינוי רשומה במקור הנתונים גלידה: העמודה מזהה של הרשומה שיש לשנות מכילה את הערך 1. (הרשומה שוקולד היא בעלת המזהה הזה.) הערך בעמודה כמות משתנה ל- 400.	{ ID: 1, Flavor: "Chocolate", כמות: 400 } הערך של שוקולד במקור הנתונים של IceCream שונה.
Patch( גלידה, ברירת מחדל ( גלידה ) , { טעם: "תות" } )	יצירת רשומה במקור הנתונים גלידה: העמודה מזהה מכילה את הערך 3, שמקור הנתונים יוצר אוטומטית. העמודה כמות מכילה 0, שהוא ערך ברירת המחדל עבור עמודה זו במקור הנתונים גלידה, כפי שהפונקציה Defaults מציינת. העמודה טעם מכילה את הערך תות שדה.	{ ID: 3, Flavor: "Strawberry", כמות: 0 } הערך של Strawberry במקור הנתונים של IceCream נוצר.

לאחר הערכת הנוסחאות הקודמות, מקור הנתונים מסתיים בערכים הבאים:

מיזוג רשומות (מחוץ למקור נתונים)

Formula	Description	Result
Patch( { שם: "ג'יימס", ציון: 90 }, { שם: "ג'ים", עבר: אמיתי } )	מיזוג שתי רשומות מחוץ למקור נתונים: הערכים בעמודה שם של כל רשומה אינם תואמים. התוצאה מכילה את הערך (חגי) ברשומה הקרובה יותר לסוף רשימת הארגומנטים במקום את הערך (עידן) ברשומה הקרובה יותר להתחלה. הרשומה הראשונה מכילה עמודה (ניקוד) שאינה קיימת בעמודה השנייה. התוצאה מכילה את העמודה הזאת עם הערך שלה (90). העמודה השנייה מכילה עמודה (עבר בהצלחה) שאינה קיימת ברשומה הראשונה. התוצאה מכילה את העמודה הזאת עם הערך שלה (true).	{ שם: "ג'ים", ציון: 90, עבר: נכון }

שינוי או יצירת סט רשומות (במקור נתונים)

כשאתה משתמש Patch בטבלאות במקום רשומות בודדות, אפשר ליצור או לשנות מספר רשומות בשיחה אחת. ערך ההחזרה הוא טבלת רשומות שמתאימה אחד לאחד עם טבלאות הקלט.

דוגמה זו מעדכנת את הכמות עבור מספר טעמים במקור הנתונים של IceCream בו-זמנית:

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

התוצאה היא טבלה עם הרשומות המעודכנות: { ID: 1, Flavor: "Chocolate", Quantity: 300 } ו { ID: 2, Flavor: "Vanilla", Quantity: 400 }- .

דוגמה זו יוצרת מספר רשומות חדשות באמצעות ברירת מחדל:

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

Note

כאשר משתמשים Patch עם טבלאות, מספר הרשומות בכל טבלת שינויים חייב להתאים למספר הרשומות בטבלת הבסיס. אחרת, מתרחשת שגיאה.

כדי לזהות שגיאות בעת שינוי מספר רשומות, השתמש ב-IfError. IfError הוא המנגנון המועדף ופועל על פני מארחי Power Fx:

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

Patch עם סוגי עמודות ב-Dataverse

הדוגמאות הבאות מתאימות במיוחד למקורות נתונים Microsoft Dataverse. צורות הרשומות משתנות לפי מקור נתונים (לדוגמה, ל-SharePoint ול-SQL Server יש פורמטים שונים).

עמודת הבחירה: כדי להגדיר עמודת בחירה, השתמש בערך enum ישירות. דוגמה זו מגדירה עמודת בחירת סטטוס בטבלת חשבונות :

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

עמודת חיפוש: כדי להגדיר עמודת חיפוש, ספק רשומה עם המפתח הראשי של הטבלה הרלוונטית. דוגמה זו מציבה את חיפוש איש הקשר הראשי ברשומת חשבונות :

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

Note

דוגמאות מסוג עמודה אלו הן ספציפיות ל-Dataverse. מקורות נתונים אחרים, כמו SharePoint או SQL Server, עשויים לדרוש צורות רשומות שונות עבור סוגי עמודות דומים. עיין בתיעוד של מקור הנתונים הספציפי שלך לפורמט הנכון.

האצלה בנוסחאות שמשתמשות בהן Patch

הפונקציה Patch עצמה אינה כפופה להאצלה כי היא כותבת למקור הנתונים במקום לשאול אותו. עם זאת, אזהרות האצלה עשויות להופיע בנוסחאות שמשתמשות Patch אם חלק בחירת הרשומה בנוסחה (כמו Filter, LookUp או ForAll) כולל שאילתה החורגת מגבלות ההאצלה של מקור הנתונים.

כאשר אתה רואה אזהרת האצלה בנוסחה שכוללת Patchאת , בדוק אם האזהרה חלה על פונקציות שליפת הנתונים ולא על Patch עצמה. למידע נוסף על האצלה, ראו הבנת האצלה באפליקציית קנבס.

שגיאות נפוצות בפונקציה Patch

כשאתה משתמש בפונקציה Patch , שגיאות עלולות להתרחש בגלל קישוריות מקורות נתונים, הרשאות או קונפליקטים בנתונים. השתמש ב-IfErrorוב-IsError כדי לזהות שגיאות ולהגיב כראוי.

• "שגיאת רשת בעת שימוש Patch בפונקציה": שגיאה זו בדרך כלל מצביעה על כך שהאפליקציה לא מצליחה להגיע למקור הנתונים. סיבות נפוצות כוללות אובדן חיבור אינטרנט, חוסר זמינות זמנית של מקור הנתונים, או הרשאות לא מספקות למשתמש הנוכחי. עטוף את השיחה Patchב-IfError כדי לספק הודעה משמעותית למשתמשים.

• "קיימים קונפליקטים עם שינויים בשרת": שגיאה זו מתרחשת כאשר משתמש או תהליך אחר משנה את אותה רשומה בין הזמן שבו האפליקציה שלך קוראת את הרשומה וכותבת את השינוי. רענון מקור הנתונים על ידי קריאה לפונקציית הרענון ונסה שוב את הפעולה.

• שגיאות הרשאה: אם למשתמש אין הרשאה ליצור או לשנות רשומות במקור הנתונים, השיחה Patch נכשלת. השתמש ב-IfError כדי לזהות שגיאות הקשורות להרשאות ולהנחות את המשתמש.

לדפוסי טיפול כללי בשגיאות, ראו טיפול בשגיאות.

שימוש ב- As או ThisRecord

השתמש במילת המפתח As או ThisRecord בנוסחה שלך כדי להימנע מהקשר הערכה מעורפל.

בדוגמה הבאה, נבחן את הראשון Lookup במשפט If . (OrderID = A[@OrderID]) מצופה להשוות את ה-in OrderId in the scope Lookup לבין OrderId האוסף A בטווח ForAll . במקרה הזה, סביר שתרצה A[@OrderId] לפתור את זה כפרמטר מקומי. אבל זה לא ברור.

Power Apps כיום מפרש גם את הצד השמאלי OrderId וגם את הצד הימני A[@OrderId] כשדה בתחום Lookup. לכן, Lookup תמיד מוצא את השורה הראשונה ב- [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, עיין במאמר Operators .