התכונה 'מטא-נתונים של מפתח' מאפשרת לשייך מטא-נתונים לישויות ולמיקומים שונים בגיליון אלקטרוני. לאחר מכן אפשר להריץ שאילתה על המטא-נתונים האלה ולהשתמש בהם כדי למצוא את האובייקטים שאליהם הם משויכים.
אפשר לשייך מטא-נתונים לשורות, לעמודות, לגיליונות או לגיליון אלקטרוני.
מטא נתונים של מפתח מאפשרים לבצע פעולות כמו:
שיוך נתונים שרירותיים לישויות ומיקומים שונים בגיליון אלקטרוני – לדוגמה, שיוך
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"
}
}
}
]
}
קריאת פריט מטא-נתונים יחיד
כדי לאחזר מטא-נתונים נפרדים של מפתח, משתמשים ב-method 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
}
}
]
}
]
}
עדכון של מטא-נתונים
כדי לעדכן את המטא-נתונים של המפתח, משתמשים ב-method 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 כדי לבחור את המטא-נתונים שאתם רוצים למחוק.
הצג דוגמה
בדוגמה הזו, אנחנו מספקים את מזהה המטא-נתונים בבקשה. התגובה תחזיר את ערכי המטא-נתונים של המפתח עבור מזהה המטא-נתונים.
כדי לוודא שהמטא-נתונים של המפתח הוסרו, משתמשים ב-method spreadsheets.developerMetadata.get ומציינים את מזהה המטא-נתונים שנמחק. אתם אמורים לקבל את התשובה 404: Not Found עם קוד הסטטוס HTTP, עם ההודעה "אין מטא-נתונים של מפתח עם המזהה 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 תואם.
אחזור של ערכי תאים לפי מטא-נתונים
על מנת לקבל ערכי תאים לפי מטא-נתונים, צריך להשתמש במתודה 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. תצטרכו לציין את מזהה הגיליון האלקטרוני ומסנן נתונים אחד או יותר שתואמים למטא-נתונים.
הבקשה הזו פועלת כבקשת 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
}
עדכון ערכים לפי מטא-נתונים
כדי לעדכן ערכי תאים שתואמים למטא-נתונים ספציפיים, צריך להשתמש במתודה 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"
]
}
מגבלות על אחסון של מטא-נתונים
יש הגבלה על המספר הכולל של מטא-נתונים שאפשר לשמור בגיליון אלקטרוני. המגבלה הזו נמדדת בתווים ומורכבת מ-2 רכיבים:
| פריט | הקצאת מגבלת אחסון |
|---|---|
| גיליון אלקטרוני | 30,000 תווים |
| כל גיליון בתוך גיליון אלקטרוני | 30,000 תווים |
הגיליון האלקטרוני יכול לשמור עד 30,000 תווים. בנוסף, אפשר לאחסן בכל גיליון אלקטרוני 30,000 תווים לכל גיליון (30,000 לגיליון 1, 30,000 לגיליון 2 וכן הלאה). כלומר, גיליון אלקטרוני שכולל 3 דפים יכול להכיל עד 120,000 תווים של המטא-נתונים של המפתח.
כל תו במאפייני המפתח והערך של אובייקט developerMetadata נכלל במגבלה הזו.