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