ฟีเจอร์ข้อมูลเมตาของนักพัฒนาซอฟต์แวร์ช่วยให้คุณเชื่อมโยงข้อมูลเมตากับเอนทิตีและตำแหน่งต่างๆ ในสเปรดชีตได้ จากนั้นคุณจะค้นหาข้อมูลเมตานี้และใช้ค้นหาออบเจ็กต์ที่เชื่อมโยงอยู่ได้
คุณจะเชื่อมโยงข้อมูลเมตากับแถว คอลัมน์ ชีต หรือสเปรดชีตได้
ข้อมูลเมตาของนักพัฒนาซอฟต์แวร์ช่วยให้คุณดำเนินการต่างๆ ได้ เช่น
เชื่อมโยงข้อมูลที่กำหนดเองกับเอนทิตีและสถานที่ต่างๆ ในสเปรดชีต - เช่น เชื่อมโยง
totals
กับคอลัมน์ D หรือresponseId = 1234
กับแถว 7ค้นหาตำแหน่งและข้อมูลทั้งหมดที่เชื่อมโยงกับคีย์หรือแอตทริบิวต์ข้อมูลเมตาหนึ่งๆ - เช่น หากมีคีย์
totals
ที่เชื่อมโยงกับคอลัมน์ D หรือระบุresponseId
ให้แสดงแถวทั้งหมดที่มีข้อมูลเมตาresponseId
และค่าข้อมูลเมตาที่เชื่อมโยงกับคอลัมน์ดังกล่าวค้นหาข้อมูลทั้งหมดที่เชื่อมโยงกับเอนทิตีหรือสถานที่ที่เฉพาะเจาะจง - เช่น ในคอลัมน์ D จะแสดงข้อมูลเมตาทั้งหมดที่เชื่อมโยงกับสถานที่นั้น
ดึงค่าในตำแหน่งโดยการระบุข้อมูลเมตาที่เกี่ยวข้อง - เช่น เมื่อ
totals
แสดงผลค่าที่มีอยู่ในคอลัมน์หรือแถวที่เกี่ยวข้อง หรือให้summary
แสดงผลตามทรัพยากรชีตที่เกี่ยวข้องอัปเดตค่าในสถานที่โดยการระบุข้อมูลเมตาที่เกี่ยวข้อง - เช่น อัปเดตค่าโดยระบุรหัสข้อมูลเมตาแทนการอัปเดตค่าในแถวผ่านรูปแบบ A1
อ่านและเขียนข้อมูลเมตา
ทรัพยากร spreadsheets.developerMetadata เพื่อเข้าถึงข้อมูลเมตาของนักพัฒนาซอฟต์แวร์ที่เชื่อมโยงกับตำแหน่งหรือวัตถุในสเปรดชีต
เกี่ยวกับข้อมูลเมตาของนักพัฒนาแอป
ส่วนนี้จะอธิบายแง่มุมที่สำคัญของข้อมูลเมตาของนักพัฒนาซอฟต์แวร์ที่คุณควรพิจารณาเมื่อทำงานกับ Sheets 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 เป็น "เท็จ" ในคำขอ การตอบกลับจะแสดงทั้งพร็อพเพอร์ตี้ของสเปรดชีตและชีต
คำขอ
{ "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 ตัวต่อแผ่นงาน 1 แผ่นในสเปรดชีต (30,000 ตัวสำหรับแผ่นงานที่ 1 และ 30,000 ตัวสำหรับแผ่นงาน 2 เป็นต้น) ดังนั้นสเปรดชีตที่มี 3 หน้าจะมีข้อมูลเมตาของนักพัฒนาซอฟต์แวร์ได้สูงสุด 120,000 อักขระ
อักขระแต่ละตัวในแอตทริบิวต์คีย์และค่าของออบเจ็กต์ developerMetadata
จะนับรวมในขีดจำกัดนี้