התכונה 'מטא-נתונים' מאפשרת לכם לשייך מטא-נתונים לישויות ולמיקומים שונים בגיליון אלקטרוני. לאחר מכן אפשר להריץ שאילתות על המטא-נתונים האלה ולהשתמש בהם כדי למצוא את האובייקטים שהם משויכים אליהם.
אפשר לשייך מטא נתונים לשורות, לעמודות, לגיליונות או לגיליון אלקטרוני.
אתם יכולים ליצור מטא-נתונים כדי לבצע פעולות כמו:
שיוך נתונים שרירותיים לישויות ולמיקומים שונים בגיליון אלקטרוני: לדוגמה, שיוך
totalsלעמודה D או שיוךresponseId = 1234לשורה 7.חיפוש של כל המיקומים והנתונים שמשויכים למפתח או למאפיין מסוים של מטא-נתונים: לדוגמה, אם המפתח הוא
totalsשמשויך לעמודה D או אם המאפיין הואresponseId, המערכת תחזיר את כל השורות עם המטא-נתוניםresponseIdואת ערך המטא-נתונים שמשויך להן.חיפוש כל הנתונים שמשויכים לישות או למיקום מסוימים: לדוגמה, אם נתונה עמודה D, המערכת תחזיר את כל המטא-נתונים שמשויכים למיקום הזה.
אחזור ערכים במיקום מסוים על ידי ציון מטא-נתונים משויכים: לדוגמה, בהינתן
totals, מחזירה ייצוג של הערכים שכלולים בעמודה או בשורה המשויכות, או בהינתןsummary, מחזירה ייצוג של משאב הגיליון המשויך.עדכון ערכים במיקום מסוים על ידי ציון מטא-נתונים משויכים: לדוגמה, במקום לעדכן את הערכים בשורה באמצעות סימון A1, אפשר לעדכן את הערכים על ידי ציון מזהה מטא-נתונים.
קריאה וכתיבה של מטא-נתונים
המשאב spreadsheets.developerMetadata מספק גישה למטא-נתונים שמשויכים למיקום או לאובייקט בגיליון אלקטרוני.
מידע על מטא-נתונים
בקטע הזה מתוארים כמה היבטים חשובים של מטא-נתונים שכדאי להביא בחשבון כשעובדים עם Sheets API.
מטא-נתונים כתגים: שימוש אחד במטא-נתונים של מפתחים הוא תג שנותן שם למיקום בגיליון האלקטרוני באמצעות מפתח ומיקום בלבד. לדוגמה, אפשר לשייך את
headerRowלשורה מסוימת או אתtotalsלעמודה מסוימת בגיליון. אפשר להשתמש בתגים כדי לקשור באופן סמנטי חלקים של גיליון אלקטרוני לשדות בכלי או במסד נתונים של צד שלישי, כך ששינויים בגיליון האלקטרוני לא ישברו את האפליקציה.מטא-נתונים כמאפיינים: מטא-נתונים שנוצרים על ידי ציון מפתח, מיקום וערך, ופועלים כצמד מפתח/ערך שמשויך למיקום הזה בגיליון. לדוגמה, אפשר לשייך:
formResponseId = resp123עם שורהlastUpdated = 1477369882עם עמודה
כך אפשר לאחסן נתונים מסוימים בהתאמה אישית, שמשויכים לאזורים או לנתונים ספציפיים בגיליון אלקטרוני, ולגשת אליהם.
מטא-נתונים של פרויקט לעומת מטא-נתונים גלויים של מסמך: כדי למנוע מפרויקט מפתח אחד להפריע למטא-נתונים של פרויקט אחר, יש שני סוגים של מטא-נתונים
visibility:projectו-document. כשמשתמשים ב-Sheets API, אפשר לראות את המטא-נתונים של הפרויקט רק מתוך פרויקט Google Cloud שבו הם נוצרו, ורק ממנו אפשר לגשת אליהם. אפשר לגשת למטא-נתונים של המסמך מכל פרויקט ב-Google Cloud שיש לו גישה למסמך.שאילתות שלא מציינות במפורש את רמת החשיפה מחזירות מטא נתונים של מסמכים תואמים ומטא נתונים של פרויקטים תואמים עבור הפרויקט ב-Google Cloud שממנו נשלחת הבקשה.
ייחודיות: מפתחות מטא-נתונים לא צריכים להיות ייחודיים, אבל
metadataIdחייבים להיות שונים. אם יוצרים מטא-נתונים ולא מציינים את שדה המזהה שלהם, ה-API מקצה מזהה. אפשר להשתמש במזהה הזה כדי לזהות את המטא-נתונים, ואפשר להשתמש במפתחות ובמאפיינים אחרים כדי לזהות קבוצות של מטא-נתונים.
יצירת מטא-נתונים
כדי ליצור מטא-נתונים, משתמשים בשיטה batchUpdate במשאב spreadsheets ומספקים CreateDeveloperMetadataRequest עם הערכים metadataKey, location ו-visibility מהמשאב spreadsheets.developerMetadata. אפשר גם לציין metadataValue או metadataId.
אם תציינו מזהה שכבר נמצא בשימוש, הבקשה תיכשל. אם לא מספקים מזהה, ה-API מקצה מזהה.
בדוגמה הזו, אנחנו מספקים מפתח, ערך ושורה בבקשה. התגובה מחזירה את ערכי המטא-נתונים של המפתח, בנוסף למזהה המטא-נתונים שהוקצה.
בקשה
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}תשובה
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
}
}
]
}קריאת פריט מטא-נתונים יחיד
כדי לאחזר מטא-נתונים ייחודיים של מפתח, משתמשים בשיטה spreadsheets.developerMetadata.get ומציינים את spreadsheetId שמכיל את המטא-נתונים ואת metadataId הייחודי של המטא-נתונים של המפתח.
בקשה
בדוגמה הזו, אנחנו מציינים בבקשה את מזהה הגיליון האלקטרוני ואת מזהה המטא-נתונים. התגובה מחזירה את ערכי מטא הנתונים של המפתח עבור מזהה מטא הנתונים.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/developerMetadata/METADATA_ID
תשובה
{
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}קריאה של כמה פריטי מטא-נתונים
כדי לאחזר כמה פריטים של מטא-נתונים למפתחים, משתמשים בשיטה spreadsheets.developerMetadata.search. צריך לציין DataFilter שתואם למטא-נתונים קיימים בשילוב כלשהו של מאפיינים, כמו מפתח, ערך, מיקום או חשיפה.
בדוגמה הזו, אנחנו מספקים כמה מזהי מטא נתונים בבקשה. התגובה מחזירה את ערכי המטא-נתונים של המפתח לכל מזהה מטא-נתונים.
בקשה
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}תשובה
{
"matchedDeveloperMetadata": [
{
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Revenue",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
},
{
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}עדכון של מטא-נתונים
כדי לעדכן את המטא-נתונים של המפתח, משתמשים בשיטה
spreadsheets.batchUpdate ומספקים UpdateDeveloperMetadataRequest.
צריך לציין DataFilter שמטרתו לעדכן את המטא-נתונים, משאב spreadsheets.developerMetadata עם הערכים החדשים ומסכת שדות שמתארת את השדות שצריך לעדכן.
בדוגמה הזו, אנחנו מספקים את מזהה המטא-נתונים, מזהה הגיליון ומפתח מטא-נתונים חדש בבקשה. התגובה מחזירה את ערכי המטא-נתונים של המפתח, וגם את מפתח המטא-נתונים המעודכן.
בקשה
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"developerMetadata": {
"location": {
"sheetId": SHEET_ID
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}תשובה
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}מחיקת מטא-נתונים
כדי למחוק מטא-נתונים של מפתח, צריך להשתמש בשיטה batchUpdate ולספק DeleteDeveloperMetadataRequest.
צריך לציין DataFilter כדי לבחור את המטא-נתונים שרוצים למחוק.
בדוגמה הזו, אנחנו מציינים את מזהה המטא-נתונים בבקשה. התגובה מחזירה את ערכי מטא הנתונים של המפתח עבור מזהה מטא הנתונים.
כדי לוודא שמטא-הנתונים של המפתח הוסרו, משתמשים בשיטה spreadsheets.developerMetadata.get ומציינים את מזהה המטא-נתונים שנמחקו. צריכה להתקבל תגובה עם קוד סטטוס HTTP 404: Not Found וההודעה 'אין מטא-נתונים של מפתח עם המזהה METADATA_ID'.
בקשה
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
}
}
]
}תשובה
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}קריאה וכתיבה של ערכים שמשויכים למטא-נתונים
אפשר גם לאחזר ולעדכן ערכים בתאים בשורות ובעמודות על ידי ציון המטא-נתונים המשויכים למפתחים והערכים שרוצים לעדכן. כדי לעשות את זה, משתמשים באחת מהשיטות הבאות עם DataFilter תואם.
אחזור ערכי תאים לפי מטא-נתונים
כדי לקבל ערכי תאים לפי מטא-נתונים, משתמשים בשיטה spreadsheets.values.batchGetByDataFilter. צריך לציין את מזהה הגיליון האלקטרוני ומסנן נתונים אחד או יותר שתואמים למטא-נתונים.
בדוגמה הזו, אנחנו מציינים את מזהה המטא-נתונים בבקשה. התגובה מחזירה את ערכי התאים בשורה (מספר הדגם, מכירות חודשיות) של מזהה המטא-נתונים.
בקשה
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"majorDimension": "ROWS"
}תשובה
{
"spreadsheetId": SPREADSHEET_ID,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}אחזור גיליון אלקטרוני לפי מטא-נתונים
כשמאחזרים גיליון אלקטרוני, אפשר להחזיר קבוצת משנה של נתונים באמצעות השיטה spreadsheets.getByDataFilter. צריך לציין את מזהה הגיליון האלקטרוני ומסנן נתונים אחד או יותר שתואמים למטא-נתונים.
הבקשה הזו פועלת כמו בקשת GET רגילה של גיליון אלקטרוני, אבל רשימת המטא-נתונים שתואמת למסנני הנתונים שצוינו קובעת אילו גיליונות, נתוני רשת ומשאבי אובייקטים אחרים עם מטא-נתונים יוחזרו. אם ההגדרה includeGridData מוגדרת כ-True, גם נתוני הרשת שחופפים לטווחים שצוינו יוחזרו לגיליון. המערכת מתעלמת מהשדה includeGridData אם מוגדרת מסכת שדות בבקשה.
בדוגמה הזו, אנחנו מציינים את מזהה המטא-נתונים ומגדירים את includeGridData כ-false בבקשה. התשובה מחזירה את המאפיינים של הגיליון האלקטרוני ושל הגיליון.
בקשה
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"includeGridData": false
}תשובה
{ "spreadsheetId": SPREADSHEET_ID, "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": SHEET_ID, "title": "Sheet7", "index": 7, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26 } } } ], "spreadsheetUrl": SPREADSHEET_URL }
עדכון ערכים לפי מטא-נתונים
כדי לעדכן ערכים של תאים שתואמים למטא-נתונים ספציפיים, משתמשים בשיטה spreadsheets.values.batchUpdateByDataFilter. צריך לציין את מזהה הגיליון האלקטרוני, valueInputOption, וערך אחד או יותר של DataFilterValueRange שמתאימים למטא-נתונים.
בדוגמה הזו, אנחנו מספקים את מזהה המטא-נתונים ואת ערכי השורה המעודכנים בבקשה. התשובה תחזיר גם את הנכסים המעודכנים וגם את הנתונים של מזהה המטא-נתונים.
בקשה
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}תשובה
{
"spreadsheetId": SPREADSHEET_ID,
"totalUpdatedRows": 1,
"totalUpdatedColumns": 2,
"totalUpdatedCells": 2,
"totalUpdatedSheets": 1,
"responses": [
{
"updatedRange": "Sheet7!A7:B7",
"updatedRows": 1,
"updatedColumns": 2,
"updatedCells": 2,
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"updatedData": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
}
]
}מחיקת ערכים לפי מטא-נתונים
כדי לנקות ערכי תאים שתואמים למטא-נתונים ספציפיים, משתמשים בשיטה spreadsheets.values.batchClearByDataFilter. כדי לבחור את המטא-נתונים שרוצים למחוק, צריך לציין מסנן נתונים.
בקשה
בדוגמה הזו, אנחנו מציינים את מזהה המטא-נתונים בבקשה. התשובה מחזירה את המזהה של הגיליון האלקטרוני ואת הטווחים שנוקו.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}תשובה
{
"spreadsheetId": SPREADSHEET_ID,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}מגבלות אחסון של מטא-נתונים
יש מגבלה על הכמות הכוללת של מטא-נתונים שאפשר לאחסן בגיליון אלקטרוני. המגבלה הזו נמדדת בתווים ומורכבת משני רכיבים:
| פריט | הקצאת מגבלת אחסון |
|---|---|
| גיליון אלקטרוני | 30,000 תווים |
| כל גיליון בגיליון אלקטרוני | 30,000 תווים |
אפשר לשמור עד 30,000 תווים בגיליון האלקטרוני. בנוסף, אפשר לאחסן 30,000 תווים לכל גיליון בתוך גיליון אלקטרוני (30,000 לגיליון הראשון, 30,000 לגיליון השני וכן הלאה). לכן, גיליון אלקטרוני עם שלושה גיליונות יכול להכיל עד 120,000 תווים של מטא-נתונים.
כל תו בשדות metadataKey ו-metadataValue של מקור המידע spreadsheets.developerMetadata נספר במסגרת המגבלה הזו.