ฟีเจอร์ข้อมูลเมตาของนักพัฒนาซอฟต์แวร์ช่วยให้คุณเชื่อมโยงข้อมูลเมตากับเอนทิตีและตำแหน่งต่างๆ ในสเปรดชีตได้ จากนั้นคุณจะค้นหาข้อมูลเมตานี้และใช้เพื่อ ค้นหาออบเจ็กต์ที่เชื่อมโยงกับข้อมูลเมตานี้ได้
คุณเชื่อมโยงข้อมูลเมตากับแถว คอลัมน์ ชีต หรือสเปรดชีตได้
ข้อมูลเมตาของนักพัฒนาแอปช่วยให้คุณดำเนินการต่างๆ ได้ เช่น
เชื่อมโยงข้อมูลที่กำหนดเองกับเอนทิตีและสถานที่ต่างๆ ในสเปรดชีต เช่น เชื่อมโยง
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
จะนับรวมในขีดจำกัดนี้