התכונה 'מטא-נתונים למפתחים' מאפשרת לשייך מטא-נתונים לישויות ולמיקומים שונים בגיליון אלקטרוני. אחר כך אפשר לשלוח שאילתה לגבי המטא-נתונים האלה ולהשתמש בהם כדי למצוא את האובייקטים שהם משויכים אליהם.
אפשר לשייך מטא נתונים לשורות, לעמודות, לגיליונות או לגיליון אלקטרוני.
מטא-נתונים של מפתחים מאפשרים לכם לבצע פעולות כמו:
שיוך נתונים שרירותיים לישויות ולמיקומים שונים בגיליון אלקטרוני – לדוגמה, שיוך
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 מקצה מזהה. אפשר להשתמש במזהה הזה כדי לזהות את המטא-נתונים, ובמפתחות ובמאפיינים אחרים כדי לזהות קבוצות של מטא-נתונים.
יצירת מטא-נתונים
כדי ליצור מטא-נתונים, משתמשים בשיטה 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"
}קריאה של כמה פריטי מטא-נתונים
כדי לאחזר כמה פריטים של מטא-נתונים למפתחים, משתמשים בשיטה 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"
}
]
}
}
]
}מחיקת מטא-נתונים
כדי למחוק מטא-נתונים של מפתח, משתמשים בשיטה batchUpdate ומספקים DeleteDeveloperMetadataRequest.
כדי לבחור את המטא-נתונים שרוצים למחוק, צריך לציין DataFilter.
בדוגמה הזו, אנחנו מציינים את מזהה המטא-נתונים בבקשה. התגובה מחזירה את ערכי מטא הנתונים של המפתח למזהה מטא הנתונים.
כדי לוודא שמטא-הנתונים של המפתח הוסרו, משתמשים בשיטה 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 לגיליון הראשון, 30,000 לגיליון השני וכן הלאה). לכן, גיליון אלקטרוני עם 3 דפים יכול להכיל עד 120,000 תווים של מטא-נתונים של מפתחים.
כל תו במאפייני המפתח והערך של אובייקט developerMetadata נספר כחלק מהמגבלה הזו.