ฟีเจอร์ข้อมูลเมตาของนักพัฒนาแอปช่วยให้คุณเชื่อมโยงข้อมูลเมตากับเอนทิตีและสถานที่ต่างๆ ในสเปรดชีตได้ จากนั้นคุณสามารถค้นหาข้อมูลเมตานี้และใช้เพื่อค้นหาออบเจ็กต์ที่เชื่อมโยงอยู่
คุณสามารถเชื่อมโยงข้อมูลเมตากับแถว คอลัมน์ ชีต หรือสเปรดชีตได้
ข้อมูลเมตาของนักพัฒนาแอปช่วยให้คุณดำเนินการต่างๆ ได้ เช่น
เชื่อมโยงข้อมูลที่ไม่เจาะจงกับเอนทิตีและตำแหน่งต่างๆ ในสเปรดชีต เช่น เชื่อมโยง
totals
กับคอลัมน์ D หรือresponseId = 1234
กับแถว 7ค้นหาตำแหน่งและข้อมูลทั้งหมดที่เชื่อมโยงกับคีย์หรือแอตทริบิวต์ข้อมูลเมตาที่เฉพาะเจาะจง เช่น เมื่อระบุคีย์
totals
ที่เชื่อมโยงกับคอลัมน์ D หรือระบุresponseId
ระบบจะแสดงผลแถวทั้งหมดที่มีข้อมูลเมตาresponseId
และค่าข้อมูลเมตาที่เชื่อมโยงกับแถวเหล่านั้นค้นหาข้อมูลทั้งหมดที่เชื่อมโยงกับเอนทิตีหรือสถานที่หนึ่งๆ เช่น แสดงผลข้อมูลเมตาทั้งหมดที่เชื่อมโยงกับสถานที่นั้นในคอลัมน์ D
ดึงข้อมูลค่าในตำแหน่งโดยระบุข้อมูลเมตาที่เชื่อมโยง เช่น เมื่อระบุ
totals
ให้แสดงค่าที่อยู่ในคอลัมน์หรือแถวที่เชื่อมโยง หรือเมื่อระบุsummary
ให้แสดงทรัพยากรชีตที่เชื่อมโยงอัปเดตค่าในตำแหน่งโดยระบุข้อมูลเมตาที่เกี่ยวข้อง เช่น แทนที่จะอัปเดตค่าในแถวผ่านรูปแบบ A1 ให้อัปเดตค่าโดยระบุรหัสข้อมูลเมตา
อ่านและเขียนข้อมูลเมตา
ทรัพยากร spreadsheets.developerMetadata ให้สิทธิ์เข้าถึงข้อมูลเมตาของนักพัฒนาแอปที่เชื่อมโยงกับสถานที่หรือออบเจ็กต์ในสเปรดชีต
เกี่ยวกับข้อมูลเมตาของนักพัฒนาแอป
ส่วนนี้จะอธิบายแง่มุมสําคัญบางอย่างของข้อมูลเมตาของนักพัฒนาแอปที่คุณควรพิจารณาเมื่อทํางานกับชีต API
ข้อมูลเมตาเป็นแท็ก
การใช้ข้อมูลเมตาของนักพัฒนาแอปอย่างหนึ่งคือแท็กที่ตั้งชื่อตำแหน่งในสเปรดชีตโดยใช้เพียงคีย์และตำแหน่ง ตัวอย่างเช่น คุณสามารถเชื่อมโยง headerRow
กับแถวที่เจาะจง หรือเชื่อมโยง totals
กับคอลัมน์ที่เจาะจงภายในชีต คุณสามารถใช้แท็กเพื่อเชื่อมโยงส่วนต่างๆ ของสเปรดชีตกับช่องในเครื่องมือหรือฐานข้อมูลของบุคคลที่สามตามความหมาย เพื่อให้การเปลี่ยนแปลงในสเปรดชีตไม่ทำให้แอปใช้งานไม่ได้
ข้อมูลเมตาเป็นพร็อพเพอร์ตี้
ข้อมูลเมตาที่สร้างโดยการระบุคีย์ ตําแหน่ง และค่าจะทําหน้าที่เป็นคู่คีย์-ค่าที่เชื่อมโยงกับตําแหน่งนั้นในสเปรดชีต ตัวอย่างเช่น คุณสามารถเชื่อมโยงสิ่งต่อไปนี้
formResponseId = resp123
ที่มีแถวlastUpdated = 1477369882
ที่มีคอลัมน์
ซึ่งช่วยให้คุณจัดเก็บและเข้าถึงพร็อพเพอร์ตี้ที่มีชื่อที่กำหนดเองซึ่งเชื่อมโยงกับพื้นที่หรือข้อมูลหนึ่งๆ ในสเปรดชีตได้
ข้อมูลเมตาที่มองเห็นได้ของโปรเจ็กต์เทียบกับเอกสาร
เพื่อป้องกันไม่ให้โปรเจ็กต์ของนักพัฒนาแอปรายหนึ่งรบกวนข้อมูลเมตาของอีกรายหนึ่ง การตั้งค่าข้อมูลเมตา visibility
มี 2 รายการ ได้แก่ 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 โดยระบุรหัสข้อมูลเมตาที่ลบ คุณควรได้รับการตอบกลับรหัสสถานะ HTTP 404: Not Found
พร้อมข้อความระบุว่า "ไม่มีข้อมูลเมตาของนักพัฒนาแอปที่มีรหัส 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 คุณจะต้องระบุรหัสสเปรดชีตและตัวกรองข้อมูลอย่างน้อย 1 รายการที่ตรงกับข้อมูลเมตา
แสดงตัวอย่าง
ในตัวอย่างนี้ เราจะระบุรหัสข้อมูลเมตาในคำขอ การตอบกลับจะแสดงค่าเซลล์แถว (หมายเลขรุ่น ยอดขายรายเดือน) สำหรับรหัสข้อมูลเมตา
คำขอ
{ "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 คุณจะต้องระบุรหัสสเปรดชีตและตัวกรองข้อมูลอย่างน้อย 1 รายการที่ตรงกับข้อมูลเมตา
คำขอนี้ทํางานเป็นคําขอ "GET สเปรดชีต" ปกติ ยกเว้นรายการข้อมูลเมตาที่ตรงกับตัวกรองข้อมูลที่ระบุจะกําหนดชีต ข้อมูลตารางกริด และทรัพยากรออบเจ็กต์อื่นๆ ที่มีข้อมูลเมตาที่จะแสดง หากตั้งค่า includeGridData
เป็น "จริง" ระบบจะแสดงผลข้อมูลตารางกริดที่ตัดกับช่วงตารางกริดที่ระบุสำหรับชีตด้วย
แสดงตัวอย่าง
ในตัวอย่างนี้ เราจะระบุรหัสข้อมูลเมตาและตั้งค่า 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
อย่างน้อย 1 รายการที่ตรงกับข้อมูลเมตา
แสดงตัวอย่าง
ในตัวอย่างนี้ เราจะระบุรหัสข้อมูลเมตาและค่าแถวที่อัปเดตแล้วในคําขอ การตอบกลับจะแสดงทั้งพร็อพเพอร์ตี้ที่อัปเดตและข้อมูลสําหรับรหัสข้อมูลเมตา
คำขอ
{ "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
จะนับรวมอยู่ในขีดจํากัดนี้