עדכון תווית

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

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

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

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

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

• תווית Properties
• Field אובייקטים וסוגי שדות
• בחירה Choice ואפשרות בחירה Properties

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

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

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

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

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

עדכון בקשות

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

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

מסיכות שדות

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

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

דוגמה

כדי לעדכן תווית, משתמשים ב-method ‏delta במשאב labels.

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

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

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

• תווית title דרך אובייקט Properties

• אובייקט אחד או יותר של Field.

• משאב labels שמייצג את התווית. הוא מכיל את name ואת id, שהוא מזהה ייחודי של התווית בכל העולם.

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

בדוגמת הקוד הבאה אפשר לראות איך משתמשים בתווית id כדי לעדכן את התווית הנכונה:

Python

body = {
    'useAdminAccess': True,
    'requests': [
        {
            'updateLabel': {
                'properties': {
                    'title': 'TITLE'
                },
                'updateMask': 'title'
            }
        },
        {
            'createField': {
                'field': {
                    'properties': {
                        'displayName': 'DISPLAY_NAME'
                    },
                    'textOptions': {}
                }
            }
        }
    ],
    'view': 'LABEL_VIEW_FULL'
}

response = service.labels().delta(
    body=body,
    name='labels/ID'
).execute()

Node.js

var body = {
  'useAdminAccess': true,
  'requests': [
    {
      'updateLabel': {
        'properties': {
          'title': 'TITLE'
        },
        'updateMask': 'title'
      }
    },
    {
      'createField': {
        'field': {
          'properties': {
            'displayName': 'DISPLAY_NAME'
          },
          'textOptions': {}
        }
      }
    }
  ],
  'view': 'LABEL_VIEW_FULL'
};

service.labels.delta({
  name: 'labels/ID',
  requestBody: body
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

מחליפים את מה שכתוב בשדות הבאים:

• TITLE: שם התווית.
• ‫DISPLAY_NAME: השם המוצג של השדה.
• ‫ID: המזהה של התווית.

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