עדכון תווית

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

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

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

עדכון אובייקטים של תוויות

תווית כוללת סוגים רבים אחרים של אובייקטים שאפשר לעדכן, כמו:

• מאפייני התווית
• שדות וסוגי שדות
• אפשרויות בחירה ומאפיינים של אפשרויות בחירה

אלה רק חלק מהאובייקטים הרבים ששולטים במראה ובפעולה של תווית.

קטגוריות של פעולות

הפעולות הבאות שנתמכות על ידי השיטה labels.delta ניתנות לקיבוץ לקטגוריות הרחבות הבאות:

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

הקטגוריות האלה משמשות בקטע הבא לתיאור ההתנהגות של פעולות ספציפיות.

בקשות לעדכון

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

סוג הבקשה
מאפייני התווית	עדכון UpdateLabelPropertiesRequest
שדה	יצירה CreateFieldRequest עדכון UpdateFieldPropertiesRequest UpdateFieldTypeRequest הפעלה EnableFieldRequest השבתה DisableFieldRequest מחיקה DeleteFieldRequest
אפשרות בחירה	יצירה CreateSelectionChoiceRequest עדכון UpdateSelectionChoicePropertiesRequest הפעלה EnableSelectionChoiceRequest השבתה DisableSelectionChoiceRequest מחיקה DeleteSelectionChoiceRequest

מסיכות שדות

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

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

.

דוגמה

כדי לעדכן תווית, משתמשים בשיטה delta באוסף labels.

צריך לציין גם:

• ‫useAdminAccess is true כדי להשתמש בפרטי הכניסה של האדמין של המשתמש. השרת מוודא שהמשתמש הוא אדמין של התווית לפני שהוא מאפשר גישה.

• תג Request שמציין את העדכונים הרלוונטיים לתווית.

• תווית title באמצעות השיטה property.

• ‫Field אחד או יותר.

• משאב Label שמייצג כל תווית. הוא מכיל משאב Name וID, שהוא מזהה ייחודי גלובלי של הלייבל.

• ‫LabelView is LABEL_VIEW_FULL כדי להגדיר את תצוגת המשאבים שמוחלת על תשובות לתוויות. ‫LABEL_VIEW_FULL מחזירה את כל השדות האפשריים.

בדוגמה הזו נשתמש ב-ID כדי לעדכן את התווית הנכונה.

Python

body = {
'use_admin_access': True,
'requests': [{
  'update_label': {
    'properties': {
      'title': 'TITLE'
    },
    'update_mask': {
      'paths': ['title']
    }
  },
}, {
  'create_field': {
    'field': {
      'properties': {
        'display_name': 'DISPLAY_NAME'
      },
      'text_options': {}
    }
  }
}],
'view': 'LABEL_VIEW_FULL'
}
response = service.labels().delta(
  body=body,
  name='labels/ID').execute()

Node.js

var body = {
  'use_admin_access': true,
  'requests': [{
    'update_label': {
      'properties': {
        'title': 'TITLE'
      },
      'update_mask': {
        'paths': ['title']
      }
    },
  }, {
    'create_field': {
      'field': {
        'properties': {
          'display_name': 'DISPLAY_NAME'
        },
        'text_options': {}
      }
    }
  }],
  'view': 'LABEL_VIEW_FULL'
};
service.labels.delta({
  'resource': body,
  'name': 'labels/ID'
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

התווית, השדה או הבחירה מתעדכנים, מזהה הגרסה של התווית גדל ב-1, והתווית מאוחסנת במסד נתונים כתווית טיוטה. לתווית יש את הערך State של PUBLISHED עם hasUnpublishedChanges=true, כלומר יש שינויים בטיוטה, אבל הם לא זמינים למשתמשים. התווית המעודכנת צריכה להיות PUBLISHED לפני שהשינויים יהיו גלויים למשתמשים. מידע נוסף זמין במאמר בנושא מחזור החיים של התווית.