התכונה 'מטא-נתונים למפתחים' מאפשרת לשייך מטא-נתונים לישויות ולמיקומים שונים בגיליון אלקטרוני. לאחר מכן תוכלו להריץ שאילתות על המטא-נתונים האלה ולהשתמש בהם כדי למצוא את האובייקטים שמשויכים אליהם.
אפשר לשייך מטא-נתונים לשורות, לעמודות, לגיליונות או לגיליון אלקטרוני.
מטא-נתונים של מפתחים מאפשרים לבצע פעולות כמו:
לשייך נתונים שרירותיים לישויות ולמיקומים שונים בגיליון אלקטרוני – לדוגמה, לשייך את הערך
totalsלעמודה D או את הערךresponseId = 1234לשורה 7.חיפוש כל המיקומים והנתונים שמשויכים למאפיין או למפתח מטא-נתונים מסוימים – לדוגמה, בהינתן המפתח
totalsשמשויך לעמודה D או בהינתן הערךresponseId, המערכת מחזירה את כל השורות עם המטא-נתונים שלresponseIdואת ערך המטא-נתונים שמשויך אליהן.חיפוש כל הנתונים שמשויכים לישות או למיקום מסוימים – לדוגמה, נתונים של עמודה D, להחזיר את כל המטא-נתונים שמשויכים למיקום הזה.
אחזור ערכים במיקום מסוים על ידי ציון מטא-נתונים משויכים – לדוגמה, אם נותנים את הערך
totals, הפונקציה מחזירה ייצוג של הערכים שמכילות העמודה או השורה המשויכות, ואם נותנים את הערךsummary, הפונקציה מחזירה ייצוג של המשאב של הגיליון האלקטרוני המשויך.עדכון ערכים במיקום מסוים על ידי ציון מטא-נתונים משויכים – לדוגמה, במקום לעדכן את הערכים בשורה באמצעות סימון A1, מעדכנים את הערכים על ידי ציון מזהה מטא-נתונים.
קריאה וכתיבה של מטא-נתונים
המשאב spreadsheets.developerMetadata מספק גישה למטא-נתונים למפתחים שמשויכים למיקום או לאובייקט בגיליון אלקטרוני.
מידע על מטא-נתונים של מפתחים
בקטע הזה מתוארים כמה היבטים מרכזיים של מטא-נתונים למפתחים שחשוב להביא בחשבון כשעובדים עם Sheets API.
מטא-נתונים בתור תגים
אחת מהשימושים במטא-נתונים למפתחים היא תג שמציין מיקום בגיליון האלקטרוני באמצעות מפתח ומיקום בלבד. לדוגמה, אפשר לשייך את headerRow לשורה מסוימת או את totals לעמודה מסוימת בגיליון. אפשר להשתמש בתגים כדי לקשר באופן סמנטי חלקים של גיליון אלקטרוני לשדות בכלי או במסד נתונים של צד שלישי, כך ששינויים בגיליון האלקטרוני לא יגרמו לשיבושים באפליקציה.
מטא-נתונים כמאפיינים
מטא-נתונים שנוצרים על ידי ציון מפתח, מיקום וערך פועלים כצמד מפתח/ערך שמשויך למיקום הזה בגיליון. לדוגמה, אפשר לשייך:
formResponseId = resp123עם שורהlastUpdated = 1477369882עם עמודה.
כך אפשר לאחסן מאפיינים עם שמות מותאמים אישית שמשויכים לאזורים או לנתונים מסוימים בגיליון אלקטרוני, ולגשת אליהם.
מטא-נתונים גלויים ברמת הפרויקט לעומת ברמת המסמך
כדי למנוע מפרויקט של מפתח אחד להפריע למטא-נתונים של פרויקט אחר, יש 2 הגדרות של visibility למטא-נתונים: project ו-document. באמצעות Sheets API, אפשר לראות את המטא-נתונים של הפרויקט רק בפרויקט הפיתוח שבו הם נוצרו. אפשר לגשת למטא-נתונים של מסמך מכל פרויקט של מפתח שיש לו גישה למסמך.
שאילתות שלא מציינות במפורש סטטוס חשיפה מחזירות מטא-נתונים תואמים של מסמכים ומטא-נתונים תואמים של פרויקט המפתח ששלח את הבקשה.
ייחודיות
מפתחות המטא-נתונים לא חייבים להיות ייחודיים, אבל הערך של metadataId חייב להיות ייחודי. אם יוצרים מטא-נתונים ומשאירים את שדה המזהה שלהם לא מוגדר, ה-API מקצה מזהה. אפשר להשתמש במזהה הזה כדי לזהות את המטא-נתונים, ואילו מפתחות ומאפיינים אחרים משמשים לזיהוי קבוצות של מטא-נתונים.
יצירת מטא-נתונים
כדי ליצור מטא-נתונים, משתמשים ב-method batchUpdate ומספקים createDeveloperMetadataRequest עם metadataKey, location ו-visibility. אפשר גם לציין metadataValue או metadataId מפורש.
אם מציינים מזהה שכבר נמצא בשימוש, הבקשה תיכשל. אם לא תספקו מזהה, ה-API יקצה מזהה.
הצג דוגמה
בדוגמה הזו, אנחנו מספקים מפתח, ערך ושורה בבקשה. התגובה מחזירה את ערכי המטא-נתונים של המפתח, וגם את מזהה המטא-נתונים שהוקצה.
בקשה
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}תגובה
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
}
}
]
}קריאת פריט מטא-נתונים יחיד
כדי לאחזר מטא-נתונים ייחודיים של מפתח, משתמשים בשיטה spreadsheets.developerMetadata.get, מציינים את spreadsheetId שמכיל את המטא-נתונים ואת metadataId הייחודי של המטא-נתונים של המפתח.
הצג דוגמה
בקשה
בדוגמה הזו, אנחנו מספקים את מזהה הגיליון האלקטרוני ואת מזהה המטא-נתונים בבקשה. התגובה מחזירה את ערכי המטא-נתונים של המפתח למזהה המטא-נתונים.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
תגובה
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}קריאה של כמה פריטים של מטא-נתונים
כדי לאחזר כמה פריטים של מטא-נתונים למפתחים, משתמשים ב-method spreadsheets.developerMetadata.search. צריך לציין DataFilter שתואם לכל מטא-נתונים קיים בכל שילוב של מאפיינים, כמו מפתח, ערך, מיקום או חשיפה.
הצג דוגמה
בדוגמה הזו, אנחנו מספקים כמה מזהי מטא-נתונים בבקשה. התגובה מחזירה את ערכי המטא-נתונים של המפתח לכל מזהה מטא-נתונים.
בקשה
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}תגובה
{
"matchedDeveloperMetadata": [
{
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Revenue",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
},
{
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}עדכון של מטא-נתונים
כדי לעדכן את המטא-נתונים של המפתח, משתמשים בשיטה spreadsheets.batchUpdate ומספקים UpdateDeveloperMetadataRequest.
צריך לציין DataFilter שמטרגט את המטא-נתונים שרוצים לעדכן, אובייקט DeveloperMetadata עם הערכים החדשים ומסכת שדה שמתארת את השדות שרוצים לעדכן.
הצג דוגמה
בדוגמה הזו, אנחנו מספקים בבקשה את מזהה המטא-נתונים, מזהה הגיליון ומפתח מטא-נתונים חדש. התגובה מחזירה את ערכי המטא-נתונים של המפתח, וגם את מפתח המטא-נתונים המעודכן.
בקשה
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}תגובה
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}מחיקה של מטא-נתונים
כדי למחוק מטא-נתונים של מפתח, משתמשים ב-method batchUpdate ומספקים את DeleteDeveloperMetadataRequest.
צריך לציין DataFilter כדי לבחור את המטא-נתונים שרוצים למחוק.
הצג דוגמה
בדוגמה הזו, אנחנו מספקים את מזהה המטא-נתונים בבקשה. התגובה מחזירה את ערכי המטא-נתונים של המפתח למזהה המטא-נתונים.
כדי לוודא שהמטא-נתונים של המפתח הוסרו, משתמשים בשיטה spreadsheets.developerMetadata.get ומציינים את מזהה המטא-נתונים שנמחקו. אמורה להתקבל תגובה עם קוד סטטוס HTTP 404: Not Found, עם ההודעה "No developer metadata with ID metadataId".
בקשה
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}תגובה
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}קריאה וכתיבה של ערכים המשויכים למטא-נתונים
אפשר גם לאחזר ולעדכן ערכים של תאים בשורות ובעמודות על ידי ציון המטא-נתונים המשויכים למפתחים והערכים שרוצים לעדכן. לשם כך, משתמשים בשיטה המתאימה שבהמשך עם DataFilter תואם.
אחזור ערכי תאים לפי מטא-נתונים
כדי לקבל ערכים של תאים לפי מטא-נתונים, משתמשים ב-method spreadsheets.values.batchGetByDataFilter. תצטרכו לציין את מזהה הגיליון האלקטרוני ומסנן נתונים אחד או יותר שתואמים למטא-נתונים.
הצג דוגמה
בדוגמה הזו, אנחנו מספקים את מזהה המטא-נתונים בבקשה. התגובה מחזירה את ערכי התאים בשורה (מספר הדגם, המכירות החודשיות) של מזהה המטא-נתונים.
בקשה
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}תגובה
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}אחזור גיליון אלקטרוני לפי מטא-נתונים
כשמאחזרים גיליון אלקטרוני, אפשר להחזיר קבוצת משנה של נתונים באמצעות השיטה spreadsheets.getByDataFilter. תצטרכו לציין את מזהה הגיליון האלקטרוני ומסנן נתונים אחד או יותר שתואמים למטא-נתונים.
הבקשה הזו פועלת כמו בקשת 'spreadsheet GET' רגילה, מלבד רשימת המטא-נתונים שתואמת למסנני הנתונים שצוינו, שמגדירה אילו גיליונות, נתוני רשת ומשאבי אובייקטים אחרים עם מטא-נתונים יחזרו. אם הערך של includeGridData מוגדר כ-true, המערכת תחזיר גם נתוני רשת שחופפים לטווחי הרשת שצוינו בגיליון.
הצג דוגמה
בדוגמה הזו, אנחנו מספקים את מזהה המטא-נתונים ומגדירים את includeGridData כ-false בבקשה. התשובה מחזירה גם את הגיליון האלקטרוני וגם את מאפייני הגיליון.
בקשה
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}תגובה
{ "spreadsheetId": spreadsheetId, "properties": { "title": "Sales Sheet", "locale": "en_US", "autoRecalc": "ON_CHANGE", "timeZone": "America/Los_Angeles", "defaultFormat": { "backgroundColor": { "red": 1, "green": 1, "blue": 1 }, "padding": { "top": 2, "right": 3, "bottom": 2, "left": 3 }, "verticalAlignment": "BOTTOM", "wrapStrategy": "OVERFLOW_CELL", "textFormat": { "foregroundColor": {}, "fontFamily": "arial,sans,sans-serif", "fontSize": 10, "bold": false, "italic": false, "strikethrough": false, "underline": false, "foregroundColorStyle": { "rgbColor": {} } }, "backgroundColorStyle": { "rgbColor": { "red": 1, "green": 1, "blue": 1 } } }, "spreadsheetTheme": { "primaryFontFamily": "Arial", "themeColors": [ { "colorType": "TEXT", "color": { "rgbColor": {} } }, { "colorType": "BACKGROUND", "color": { "rgbColor": { "red": 1, "green": 1, "blue": 1 } } }, { "colorType": "ACCENT1", "color": { "rgbColor": { "red": 0.25882354, "green": 0.52156866, "blue": 0.95686275 } } }, { "colorType": "ACCENT2", "color": { "rgbColor": { "red": 0.91764706, "green": 0.2627451, "blue": 0.20784314 } } }, { "colorType": "ACCENT3", "color": { "rgbColor": { "red": 0.9843137, "green": 0.7372549, "blue": 0.015686275 } } }, { "colorType": "ACCENT4", "color": { "rgbColor": { "red": 0.20392157, "green": 0.65882355, "blue": 0.3254902 } } }, { "colorType": "ACCENT5", "color": { "rgbColor": { "red": 1, "green": 0.42745098, "blue": 0.003921569 } } }, { "colorType": "ACCENT6", "color": { "rgbColor": { "red": 0.27450982, "green": 0.7411765, "blue": 0.7764706 } } }, { "colorType": "LINK", "color": { "rgbColor": { "red": 0.06666667, "green": 0.33333334, "blue": 0.8 } } } ] } }, "sheets": [ { "properties": { "sheetId": sheetId, "title": "Sheet7", "index": 7, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26 } } } ], "spreadsheetUrl": spreadsheetUrl }
עדכון ערכים לפי מטא-נתונים
כדי לעדכן את ערכי התאים שתואמים למטא-נתונים ספציפיים, משתמשים ב-method spreadsheets.values.batchUpdateByDataFilter. צריך לציין את מזהה הגיליון האלקטרוני, valueInputOption, ו-DataFilterValueRange אחד או יותר שתואמים למטא-נתונים.
הצג דוגמה
בדוגמה הזו, אנחנו מספקים את מזהה המטא-נתונים ואת ערכי השורות המעודכנים בבקשה. התשובה מחזירה גם את הנכסים וגם את הנתונים המעודכנים של מזהה המטא-נתונים.
בקשה
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}תגובה
{
"spreadsheetId": spreadsheetId,
"totalUpdatedRows": 1,
"totalUpdatedColumns": 2,
"totalUpdatedCells": 2,
"totalUpdatedSheets": 1,
"responses": [
{
"updatedRange": "Sheet7!A7:B7",
"updatedRows": 1,
"updatedColumns": 2,
"updatedCells": 2,
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"updatedData": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
}
]
}ניקוי ערכים לפי מטא-נתונים
כדי לנקות את ערכי התאים שתואמים למטא-נתונים ספציפיים, משתמשים בשיטה spreadsheets.values.batchClearByDataFilter. כדי לבחור את המטא-נתונים שרוצים לנקות, צריך לציין מסנן נתונים.
הצג דוגמה
בקשה
בדוגמה הזו, אנחנו מספקים את מזהה המטא-נתונים בבקשה. בתגובה מוחזר מזהה הגיליון האלקטרוני והטווחים שנמחקו.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}תגובה
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}מגבלות האחסון של מטא-נתונים
יש מגבלה על כמות המטא-נתונים הכוללת שאפשר לאחסן בגיליון אלקטרוני. המגבלה הזו נמדדת בתווים והיא מורכבת משני רכיבים:
| פריט | הקצאת מגבלת אחסון |
|---|---|
| גיליון אלקטרוני | 30,000 תווים |
| כל גיליון בתוך גיליון אלקטרוני | 30,000 תווים |
אפשר לשמור בגיליון האלקטרוני עד 30,000 תווים. בנוסף, אפשר לאחסן 30,000 תווים בכל גיליון בגיליון אלקטרוני (30,000 תווים בגיליון הראשון, 30,000 תווים בגיליון השני וכן הלאה). לכן, גיליון אלקטרוני עם 3 דפים יכול להכיל עד 120,000 תווים של מטא-נתונים של מפתח.
כל תו במאפייני המפתח והערך של אובייקט developerMetadata נספר במסגרת המגבלה הזו.