Geliştirici meta verisi özelliği, meta verileri bir e-tablodaki çeşitli öğe ve konumlarla ilişkilendirmenize olanak tanır. Ardından bu meta verileri sorgulayabilir ve ilişkili nesneleri bulmak için kullanabilirsiniz.
Meta verileri satırlar, sütunlar, sayfalar veya e-tablolarla ilişkilendirebilirsiniz.
Geliştirici üst verileri, aşağıdaki gibi işlemleri gerçekleştirmenize olanak tanır:
İstediğiniz verileri e-tablodaki çeşitli varlıklar ve konumlarla ilişkilendirin. Örneğin,
totalsdeğerini D sütunuyla veyaresponseId = 1234değerini 7. satırla ilişkilendirin.Belirli bir meta veri anahtarıyla veya özelliğiyle 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ütununda, söz konusu 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ütunda veya satırda bulunan değerlerin temsilini döndürür veyasummaryverildiğinde ilişkili E-Tablo kaynağının temsilini döndürür.İlişkili meta verileri belirterek bir konumdaki değerleri güncelleyin: Örneğin, bir satırdaki değerleri A1 gösterimi ile güncellemek yerine, meta veri kimliği belirterek değerleri güncelleyin.
Meta verileri okuma ve yazma
spreadsheets.developerMetadata kaynağı, e-tablodaki bir konum veya nesneyle ilişkili geliştirici meta verilerine erişim sağlar.
Geliştirici meta verileri hakkında
Bu bölümde, E-Tablolar API ile çalışırken göz önünde bulundurmanız gereken geliştirici meta verilerinin bazı önemli özellikleri açıklanmaktadır.
Etiket olarak meta veri
Geliştirici meta verilerinin bir kullanım alanı, yalnızca bir anahtar ve konum kullanarak e-tablodaki bir konumu adlandıran etiket'tir. Örneğin, headerRow değerini belirli bir satırla veya totals değerini bir sayfadaki belirli bir sütunla ilişkilendirebilirsiniz. E-tablonun bölümlerini üçüncü taraf bir araçtaki veya veritabanındaki alanlara anlamsal olarak bağlamak için etiketler kullanılabilir. Böylece, e-tabloda yapılan değişiklikler uygulamanızı bozmaz.
Meta verileri mülkler olarak
Anahtar, konum ve değer belirterek oluşturulan meta veriler, bir sayfadaki ilgili konumla ilişkili bir anahtar/değer çifti gibi çalışır. Örneğin, aşağıdakileri ilişkilendirebilirsiniz:
formResponseId = resp123satırlastUpdated = 1477369882sütunu ekleyin.
Bu sayede, bir e-tabloda belirli alanlar veya verilerle ilişkili özel adlandırılmış mülkleri saklayabilir ve bunlara erişebilirsiniz.
Proje ve belgede görünen meta veriler
Bir geliştirici projesinin başka bir geliştirici projesinin meta verilerini etkilemesini önlemek için 2 meta veri visibility ayarı vardır: project ve document. Sheets API'yi kullanarak proje meta verilerini yalnızca projeyi oluşturan geliştirici projesinden görebilir ve bu projeye erişebilirsiniz. Belge meta verilerine, belgeye erişimi olan tüm geliştirici projelerinden erişilebilir.
İsteği yapan geliştirici projesinin belge meta verilerini ve proje meta verilerini eşleştiren bir görünürlük döndürmeyi açıkça belirtmeyen sorgular.
Benzersizlik
Meta veri anahtarlarının benzersiz olması gerekmez ancak metadataId farklı olmalıdır. Meta veri oluşturup kimlik alanını belirtmezseniz 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 batchUpdate yöntemini kullanın ve metadataKey, location ve visibility içeren bir createDeveloperMetadataRequest gönderin. İsterseniz metadataValue veya açık metadataId belirtebilirsiniz.
Halihazırda kullanılmakta olan bir kimlik belirtirseniz istek başarısız olur. Kimlik sağlamazsanız API bir kimlik atar.
Örnek göster
Bu örnekte, istekte bir anahtar, değer ve satır sağlarız. Yanıt, bu geliştirici meta veri değerlerinin yanı sıra atanan meta veri kimliğini döndürür.
İstek
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}
Yanıt
{
"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"
}
}
}
]
}
Tek bir meta veri öğesini okuma
Tek ve farklı bir geliştirici meta verisi almak için spreadsheets.developerMetadata.get yöntemini kullanın. Bu yöntemde, meta verileri ve geliştirici meta verilerinin benzersiz metadataId değerini içeren spreadsheetId değerini belirtin.
Örnek göster
İstek
Bu örnekte, istekte e-tablo kimliğini ve meta veri kimliğini sağlıyoruz. Yanıt, meta veri kimliği için geliştirici meta veri değerlerini döndürür.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
Yanıt
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
Birden fazla meta veri öğesini okuma
Birden fazla geliştirici meta verisi öğesi almak için spreadsheets.developerMetadata.search yöntemini kullanın. Anahtar, değer, konum veya görünürlük gibi özelliklerden oluşan herhangi bir kombinasyondaki mevcut meta verilerle eşleşen bir DataFilter belirtmeniz gerekir.
Örnek göster
Bu örnekte, istekte birden fazla meta veri kimliği sağlıyoruz. Yanıt, her meta veri kimliği için geliştirici meta veri değerlerini döndürür.
İstek
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Yanıt
{
"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
}
}
]
}
]
}
Meta veriyi güncelle
Geliştirici meta verilerini güncellemek için spreadsheets.batchUpdate yöntemini kullanın ve bir UpdateDeveloperMetadataRequest sağlayın.
Güncellenecek meta verileri hedefleyen bir DataFilter, yeni değerleri içeren bir DeveloperMetadata nesnesi ve güncellenecek alanları açıklayan bir alan maskesi belirtmeniz gerekir.
Örnek göster
Bu örnekte, istekte meta veri kimliğini, sayfa kimliğini ve yeni bir meta veri anahtarı sağlıyoruz. Yanıtta bu geliştirici meta veri değerlerinin yanı sıra güncellenmiş meta veri anahtarı döndürülür.
İstek
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}
Yanıt
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
Meta verileri silme
Geliştirici meta verilerini silmek için batchUpdate yöntemini kullanın ve DeleteDeveloperMetadataRequest gönderin.
Silmek istediğiniz meta verileri seçmek için bir DataFilter belirtmeniz gerekir.
Örnek göster
Bu örnekte, istekte meta veri kimliğini sağlıyoruz. Yanıt, meta veri kimliği için geliştirici meta veri 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. "metadataId kimlikli geliştirici meta verisi yok" mesajını içeren bir 404: Not Found HTTP durum kodu yanıtı alırsınız.
İstek
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}
Yanıt
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
Meta verileriyle 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 alıp güncelleyebilirsiniz. Bunu yapmak için eşleşen bir DataFilter ile aşağıdaki uygun yöntemi 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 verileriyle eşleşen bir veya daha fazla veri filtresi belirtmeniz gerekir.
Örnek göster
Bu örnekte, istekte meta veri kimliğini sağlıyoruz. Yanıt, meta veri kimliğinin satır hücre değerlerini (model numarası, aylık satışlar) döndürür.
İstek
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}
Yanıt
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}
E-tabloyu meta verilere göre 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 verileriyle eşleşen bir veya daha fazla veri filtresi belirtmeniz gerekir.
Bu istek, belirtilen veri filtreleriyle eşleşen meta veri listesinin hangi sayfaların, ızgara verilerinin ve meta veri içeren 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 e-tablo için belirtilen ızgara aralıklarını kesiştiren ızgara verileri de döndürülür.
Örnek göster
Bu örnekte, meta veri kimliğini sağlar ve istekte includeGridData parametresini false olarak ayarlarız. Yanıt, hem e-tablo hem de sayfa özelliklerini döndürür.
İstek
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}
Yanıt
{
"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
}
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 belirtmeniz gerekir.
Örnek göster
Bu örnekte, istekte meta veri kimliğini ve güncellenmiş satır değerlerini sağlıyoruz. Yanıt, hem güncellenen özellikleri hem de meta veri kimliğine ait verileri döndürür.
İstek
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}
Yanıt
{
"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"
]
]
}
}
]
}
Meta verilere göre değerleri temizleme
Belirli meta verilerle eşleşen hücre değerlerini temizlemek için spreadsheets.values.batchClearByDataFilter yöntemini kullanın. Temizlemek istediğiniz meta verileri seçmek için bir veri filtresi belirtmeniz gerekir.
Örnek göster
İstek
Bu örnekte, istekte meta veri kimliğini sağlıyoruz. Yanıt, e-tablo kimliğini ve temizlenen aralıkları döndürür.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Yanıt
{
"spreadsheetId": spreadsheetId,
"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. Karakter sayısıyla ölçülen bu sınır 2 bileşenden oluşur:
| Öğe | Depolama alanı sınırı tahsisi |
|---|---|
| E-tablo | 30.000 karakter |
| E-tablodaki her sayfa | 30.000 karakter |
E-tabloda en fazla 30.000 karakter depolayabilirsiniz. Ayrıca, e-tablodaki her sayfa için 30.000 karakter depolayabilirsiniz (birinci sayfa için 30.000, ikinci sayfa için 30.000 vb.). Bu nedenle,3 sayfa içeren bir e-tabloda en fazla 120.000 karakter geliştirici meta verisi bulunabilir.
Bir developerMetadata nesnesinin anahtar ve değer özelliklerindeki her karakter bu sınıra dahil edilir.