Meta veri özelliği, meta verileri bir e-tablodaki çeşitli öğeler ve konumlarla ilişkilendirmenize olanak tanır. Daha sonra bu meta verileri sorgulayabilir ve ilişkili olduğu nesneleri bulmak için kullanabilirsiniz.
Meta verileri satırlar, sütunlar, sayfalar veya bir e-tabloyla ilişkilendirebilirsiniz.
Aşağıdaki gibi işlemleri gerçekleştirmek için meta veri oluşturabilirsiniz:
E-tablodaki çeşitli öğeler ve konumlarla rastgele verileri ilişkilendirme: Örneğin,
totalsöğesini D sütunuyla veyaresponseId = 1234öğesini 7. satırla ilişkilendirin.Belirli bir meta veri anahtarı veya özellikle ilişkili tüm konumları ve verileri bulma: Örneğin, D sütunuyla ilişkili
totalsanahtarı veyaresponseIdverildiğinde,responseIdmeta verilerini ve bunlarla ilişkili meta veri değerini içeren tüm satırları döndürün.Belirli bir öğe veya konumla ilişkili tüm verileri bulma: Örneğin, D sütunu verildiğinde bu konumla ilişkili tüm meta verileri döndürün.
İlişkili meta verileri belirterek bir konumdaki değerleri alma: Örneğin,
totalsverildiğinde ilişkili sütun veya satırda yer alan değerlerin bir gösterimini döndürün ya dasummaryverildiğinde ilişkili Sayfa kaynağının bir gösterimini döndürün.İlişkili meta verileri belirterek bir konumdaki değerleri güncelleme: Örneğin, bir satırdaki değerleri A1 notasyonu ile güncellemek yerine meta veri kimliği belirterek güncelleyin.
Meta verileri okuma ve yazma
spreadsheets.developerMetadata
kaynağı, bir e-tablodaki konum veya nesneyle ilişkili meta verilere erişim sağlar.
Meta veriler hakkında
Bu bölümde, E-Tablolar API'si ile çalışırken göz önünde bulundurmanız gereken meta verilerin bazı temel yönleri açıklanmaktadır.
Etiket olarak meta veriler: Geliştirici meta verilerinin bir kullanım alanı, yalnızca bir anahtar ve bir konum kullanarak e-tablodaki bir konumu adlandıran etikettir. Örneğin,
headerRowsimgesini bir sayfadaki belirli bir satırla veyatotalssimgesini belirli bir sütunla ilişkilendirebilirsiniz. Etiketler, bir e-tablonun bölümlerini üçüncü taraf bir araçtaki veya veritabanındaki alanlara anlamsal olarak bağlamak için kullanılabilir. Böylece, e-tabloda yapılan değişiklikler uygulamanızın çalışmasını engellemez.Özellik olarak meta veriler: Anahtar, konum ve değer belirtilerek oluşturulan meta veriler, bir sayfada söz konusu konumla ilişkili anahtar/değer çifti olarak işlev görür. Örneğin, şunları ilişkilendirebilirsiniz:
formResponseId = resp123satır- Sütunlu
lastUpdated = 1477369882
Bu özelliği kullanarak, bir e-tablodaki belirli alanlar veya verilerle ilişkili özel adlandırılmış özellikleri saklayıp bunlara erişebilirsiniz.
Proje ve doküman meta verilerinin görünürlüğü: Bir geliştirici projesinin başka bir projenin meta verilerine müdahale etmesini önlemek için iki meta veri
visibilityprojectvedocumentayarı vardır. E-Tablolar API'si kullanıldığında proje meta verileri yalnızca bunları oluşturan Google Cloud projesinden görülebilir ve erişilebilir. Belge meta verilerine, belgeye erişimi olan herhangi bir Google Cloud projesinden erişilebilir.Görünürlüğü açıkça belirtilmeyen sorgular, isteği gönderen Google Cloud projesi için eşleşen doküman meta verilerini ve eşleşen proje meta verilerini döndürür.
Benzersizlik: Meta veri anahtarlarının benzersiz olması gerekmez ancak
metadataIdbenzersiz olmalıdır. Meta veri oluşturup kimlik alanını belirtmeden bırakırsanız API bir kimlik atar. Bu kimlik, meta verileri tanımlamak için kullanılabilir. Anahtarlar ve diğer özellikler ise meta veri kümelerini tanımlamak için kullanılabilir.
Meta veri oluşturma
Meta veri oluşturmak için spreadsheets kaynağında batchUpdate yöntemini kullanın ve spreadsheets.developerMetadata kaynağındaki metadataKey, location ve visibility değerleriyle birlikte bir CreateDeveloperMetadataRequest sağlayın. İsteğe bağlı olarak bir metadataValue veya açık bir metadataId belirtebilirsiniz.
Zaten kullanılmakta olan bir kimlik belirtirseniz istek başarısız olur. Kimlik sağlamazsanız API bir kimlik atar.
Bu örnekte, istekte bir anahtar, değer ve satır sağlıyoruz. Yanıt, bu geliştirici meta verisi değerlerinin yanı sıra atanan meta veri kimliğini de döndürür.
İstek
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}Yanıt
{
"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"
}
}
}
]
}Tek bir meta veri öğesini okuma
Tek ve farklı bir geliştirici meta verisini almak için meta verileri içeren spreadsheetId ve geliştirici meta verilerinin benzersiz metadataId değerini belirterek spreadsheets.developerMetadata.get yöntemini kullanın.
İstek
Bu örnekte, istekte e-tablo kimliği ve meta veri kimliği sağlanmaktadır. Yanıt, meta veri kimliğinin geliştirici meta verisi değerlerini döndürür.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/developerMetadata/METADATA_ID
Yanıt
{
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}Birden fazla meta veri öğesini okuma
Birden fazla geliştirici meta verisi öğesini almak için spreadsheets.developerMetadata.search yöntemini kullanın. Anahtar, değer, konum veya görünürlük gibi özelliklerin herhangi bir kombinasyonunda mevcut meta verilerle eşleşen bir DataFilter belirtmeniz gerekir.
Bu örnekte, istekte birden fazla meta veri kimliği sağlıyoruz. Yanıt, her meta veri kimliği için geliştirici meta verisi değerlerini döndürür.
İstek
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}Yanıt
{
"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
}
}
]
}
]
}Meta veriyi güncelle
Geliştirici meta verilerini güncellemek için spreadsheets.batchUpdate yöntemini kullanın ve UpdateDeveloperMetadataRequest sağlayın.
Güncellenecek meta verileri hedefleyen bir DataFilter, yeni değerleri içeren bir spreadsheets.developerMetadata kaynağı ve güncellenecek alanları açıklayan bir alan maskesi belirtmeniz gerekir.
Bu örnekte, istekte meta veri kimliği, sayfa kimliği ve yeni bir meta veri anahtarı sağlıyoruz. Yanıtta, bu geliştirici meta verisi değerleri ve güncellenmiş meta veri anahtarı döndürülür.
İstek
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"developerMetadata": {
"location": {
"sheetId": SHEET_ID
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}Yanıt
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Meta verileri silme
Geliştirici meta verilerini silmek için batchUpdate yöntemini kullanın ve DeleteDeveloperMetadataRequest sağlayın.
Silmek istediğiniz meta verileri seçmek için bir
DataFilter belirtmeniz gerekir.
Bu örnekte, meta veri kimliği istekte sağlanır. Yanıt, meta veri kimliğinin geliştirici meta verisi değerlerini döndürür.
Geliştirici meta verilerinin kaldırıldığını onaylamak için silinen meta veri kimliğini belirterek spreadsheets.developerMetadata.get
yöntemini kullanın. "METADATA_ID kimlikli geliştirici meta verisi yok" mesajını içeren bir 404: Not Found HTTP durum kodu yanıtı almanız gerekir.
İstek
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
}
}
]
}Yanıt
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Meta verilerle ilişkili değerleri okuma ve yazma
Ayrıca, ilişkili geliştirici meta verilerini ve güncellemek istediğiniz değerleri belirterek satır ve sütunlardaki hücre değerlerini de alıp güncelleyebilirsiniz. Bunu yapmak için aşağıdaki yöntemlerden birini eşleşen bir DataFilter ile birlikte kullanın.
Meta verilere göre hücre değerlerini alma
Hücre değerlerini meta verilere göre almak için
spreadsheets.values.batchGetByDataFilter
yöntemini kullanın. E-tablo kimliğini ve meta verilerle eşleşen bir veya daha fazla veri filtresini belirtmeniz gerekir.
Bu örnekte, meta veri kimliği istekte sağlanır. Yanıt, meta veri kimliği için satır hücresi değerlerini (model numarası, aylık satışlar) döndürür.
İstek
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"majorDimension": "ROWS"
}Yanıt
{
"spreadsheetId": SPREADSHEET_ID,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}Meta verilere göre e-tablo alma
Bir e-tabloyu alırken spreadsheets.getByDataFilter yöntemini kullanarak verilerin bir alt kümesini döndürebilirsiniz. E-tablo kimliğini ve meta verilerle eşleşen bir veya daha fazla veri filtresini belirtmeniz gerekir.
Bu istek, belirtilen veri filtreleriyle eşleşen meta veri listesinin hangi sayfaların, ızgara verilerinin ve meta verili diğer nesne kaynaklarının döndürüleceğini belirlemesi dışında normal bir "e-tablo GET" isteği gibi çalışır. includeGridData doğru değerine ayarlanırsa belirtilen ızgara aralıklarıyla kesişen ızgara verileri de sayfa için döndürülür. İstek içinde bir alan maskesi ayarlanmışsa includeGridData alanı yoksayılır.
Bu örnekte, meta veri kimliğini sağlıyor ve istekte includeGridData değerini false olarak ayarlıyoruz. Yanıt, hem e-tablo hem de sayfa özelliklerini döndürür.
İstek
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"includeGridData": false
}Yanıt
{ "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 }
Değerleri meta verilere göre güncelleme
Belirli meta verilerle eşleşen hücre değerlerini güncellemek için
spreadsheets.values.batchUpdateByDataFilter
yöntemini kullanın. E-tablo kimliğini,
valueInputOption,
ve meta verilerle eşleşen bir veya daha fazla
DataFilterValueRange
değerini belirtmeniz gerekir.
Bu örnekte, meta veri kimliğini ve güncellenen satır değerlerini istekte sağlıyoruz. Yanıt, hem güncellenen özellikleri hem de meta veri kimliğinin verilerini döndürür.
İstek
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}Yanıt
{
"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"
]
]
}
}
]
}Meta verilere göre değerleri temizleme
Belirli meta verilerle eşleşen hücre değerlerini temizlemek için <0x0x0A>spreadsheets.values.batchClearByDataFilter<0x0x0A> yöntemini kullanın. Temizlemek istediğiniz meta verileri seçmek için bir veri filtresi belirtmeniz gerekir.
İstek
Bu örnekte, meta veri kimliği istekte sağlanır. Yanıt, e-tablo kimliğini ve temizlenen aralıkları döndürür.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}Yanıt
{
"spreadsheetId": SPREADSHEET_ID,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}Meta veri depolama alanı sınırları
Bir e-tabloda depolayabileceğiniz toplam meta veri miktarı sınırlıdır. Bu sınır karakter cinsinden ölçülür ve iki bileşenden oluşur:
| Öğe | Depolama alanı sınırı tahsisi |
|---|---|
| E-tablo | 30.000 karakter |
| E-tablodaki her sayfa | 30.000 karakter |
E-tablo için 30.000 karaktere kadar depolama alanı kullanabilirsiniz. Ayrıca, bir e-tablodaki her sayfa için 30.000 karakter saklayabilirsiniz (birinci sayfa için 30.000, ikinci sayfa için 30.000 vb.). Bu nedenle,üç sayfalı bir e-tablo en fazla 120.000 karakterlik meta veri içerebilir.
spreadsheets.developerMetadata kaynağının metadataKey ve metadataValue alanlarındaki her karakter bu sınıra dahil edilir.