התכונה 'מטא-נתונים' מאפשרת לכם לשייך מטא-נתונים לישויות ולמיקומים שונים בגיליון אלקטרוני. לאחר מכן אפשר להריץ שאילתות על המטא-נתונים האלה ולהשתמש בהם כדי למצוא את האובייקטים שהם משויכים אליהם.
אפשר לשייך מטא נתונים לשורות, לעמודות, לגיליונות או לגיליון אלקטרוני.
מידע על מטא-נתונים
בהמשך מפורטים כמה היבטים חשובים של מטא-נתונים שכדאי להביא בחשבון כשעובדים עם Sheets API:
מטא-נתונים כתגים: אחד השימושים במטא-נתונים של מפתחים הוא תג שנותן שם למיקום בגיליון האלקטרוני באמצעות מפתח ומיקום בלבד. לדוגמה, אפשר לשייך את
headerRowלשורה מסוימת או אתtotalsלעמודה מסוימת בגיליון. אפשר להשתמש בתגים כדי לקשור באופן סמנטי חלקים של גיליון אלקטרוני לשדות בכלי או במסד נתונים של צד שלישי, כך ששינויים בגיליון האלקטרוני לא ישברו את האפליקציה.מטא-נתונים כמאפיינים: מטא-נתונים שנוצרים על ידי ציון מפתח, מיקום וערך, ומשמשים כצמד מפתח/ערך שמשויך למיקום הזה בגיליון. לדוגמה, אפשר לשייך:
formResponseId = resp123עם שורהlastUpdated = 1477369882עם עמודה
כך אפשר לאחסן ולגשת למאפיינים מותאמים אישית עם שמות שמשויכים לאזורים או לנתונים ספציפיים בגיליון אלקטרוני.
מטא-נתונים של פרויקט לעומת מטא-נתונים של מסמך שגלויים: כדי למנוע ממטא-נתונים של פרויקט פיתוח אחד להפריע למטא-נתונים של פרויקט אחר, יש שני סוגים של מטא-נתונים
visibility:projectו-document. באמצעות Sheets API, המטא-נתוניםprojectגלויים ונגישים רק מהפרויקט ב-Google Cloud שבו הם נוצרו. אפשר לגשת למטא-נתונים שלdocumentמכל פרויקט ב-Google Cloud שיש לו גישה למסמך.שאילתות שלא מציינות באופן מפורש את
visibilityמחזירות מטא-נתונים תואמים שלdocumentומטא-נתונים תואמים שלprojectעבור פרויקט Google Cloud ששולח את הבקשה.ייחודיות: מפתחות מטא-נתונים לא חייבים להיות ייחודיים, אבל
metadataIdחייבים להיות שונים. אם יוצרים מטא-נתונים ולא מציינים את שדה המזהה שלהם, ה-API מקצה מזהה. אפשר להשתמש במזהה הזה כדי לזהות את המטא-נתונים, ובמפתחות ובמאפיינים אחרים כדי לזהות קבוצות של מטא-נתונים.החזרת מטא-נתונים באמצעות בקשות API: אובייקט
DataFilterהוא חלק מקריאה ל-API שמתאר את הנתונים שייבחרו או יוחזרו מבקשת API.באובייקט
DataFilterיחיד אפשר לציין רק סוג אחד של קריטריונים לסינון כדי לאתר נתונים:
developerMetadataLookup: בחירת נתונים שמשויכים למטא-נתונים של מפתח שצוינו, שתואמים לקריטריונים.
a1Range: בוחר נתונים שתואמים לטווח שצוין בסימון A1. לדוגמה,Sheet1!A1:B10.
gridRange: בוחר נתונים שתואמים לטווח התאים שצוין באמצעות אינדקסים מבוססי-אפס. לדוגמה,Sheet1!A3:B4 == sheetId: 123456, startRowIndex: 2, endRowIndex: 4, startColumnIndex: 0, endColumnIndex: 2.
כדי לסנן לפי כמה מיקומים או קריטריונים, אפשר להשתמש בכמה אובייקטים מסוג
DataFilterבבקשת API אחת. מציינים מערך או רשימה של אובייקטיםDataFilterבבקשת אצווה, כמו בשיטהspreadsheets.values.batchGetByDataFilter. כל טווח שתואם לאחד ממסנני הנתונים בבקשה יוחזר או ישונה.מידע נוסף מופיע במאמר קריאה וכתיבה של ערכים שמשויכים למטא-נתונים.
תרחישים לדוגמה
הנה כמה דוגמאות לתרחישי שימוש לניהול מטא-נתונים:
לשייך נתונים שרירותיים לישויות ולמיקומים שונים בגיליון אלקטרוני: לדוגמה, לשייך את
totalsלעמודה D או אתresponseId = 1234לשורה 7.חיפוש של כל המיקומים והנתונים שמשויכים למפתח או למאפיין מסוים של מטא-נתונים: לדוגמה, אם נתון המפתח הוא
totalsשמשויך לעמודה D או אם נתון המאפיין הואresponseId, המערכת תחזיר את כל השורות עם המטא-נתוניםresponseIdואת ערך המטא-נתונים שמשויך להן.מציאת כל הנתונים שמשויכים לישות או למיקום מסוימים: לדוגמה, בהינתן עמודה D, מחזירה את כל המטא-נתונים שמשויכים למיקום הזה.
אחזור ערכים במיקום על ידי ציון מטא-נתונים משויכים: לדוגמה, בהינתן
totals, מחזירה ייצוג של הערכים שכלולים בעמודה או בשורה המשויכות, או בהינתןsummary, מחזירה ייצוג של משאב הגיליון המשויך.עדכון ערכים במיקום מסוים על ידי ציון מטא-נתונים משויכים: לדוגמה, במקום לעדכן את הערכים בשורה באמצעות סימון A1, אפשר לעדכן את הערכים על ידי ציון מזהה מטא-נתונים.
קריאה וכתיבה של מטא-נתונים
המשאב spreadsheets.developerMetadata מספק גישה למטא-נתונים שמשויכים למיקום או לאובייקט בגיליון אלקטרוני. אפשר להשתמש במטא נתונים למפתחים כדי לשייך נתונים שרירותיים לחלקים שונים בגיליון אלקטרוני. המטא-נתונים נשארים משויכים למיקומים האלה גם כשעורכים את הגיליון האלקטרוני.
יצירת מטא-נתונים
כדי ליצור מטא-נתונים, משתמשים בשיטה 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 אם מוגדר field mask בבקשה.
בדוגמה הזו, אנחנו מספקים את מזהה המטא-נתונים ומגדירים את 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 נספר במסגרת המגבלה הזו.