Geliştirici meta verisi özelliği, e-tablodaki çeşitli varlıklar ve konumlarla meta verileri ilişkilendirmenize olanak tanır. Daha sonra bu meta verileri sorgulayabilir ve ilişkilendirildiği nesneleri bulmak için kullanabilirsiniz.
Meta verileri satırlar, sütunlar, sayfalar veya bir e-tablo ile ilişkilendirebilirsiniz.
Geliştirici meta verileri, aşağıdakiler gibi işlemler gerçekleştirmenize olanak tanır:
Rastgele verileri bir e-tablodaki çeşitli varlıklar ve konumlarla ilişkilendirin: Ö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ğinderesponseIdmeta verisi içeren tüm satırları ve bunlarla ilişkili meta veri değerini döndürür.Belirli bir varlık veya konumla ilişkili tüm verileri bulma - Örneğin, verilen D sütunu, bu konumla ilişkili tüm meta verileri döndürür.
İlişkili meta verileri belirterek bir konumdaki değerleri alma: Örneğin,
totals, ilişkili sütun veya satırda yer alan değerlerin temsilini döndürür veyasummarydeğeri, ilişkili e-tablo kaynağının bir 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, Sheets API ile çalışırken geliştirici meta verilerinin göz önünde bulundurmanız gereken bazı önemli yönleri açıklanmaktadır.
Etiket olarak meta veri
Geliştirici meta verilerinin bir kullanımı, e-tabloda bir konumu yalnızca bir anahtar ve konum kullanarak adlandıran bir etikettir. Örneğin, headerRow öğesini belirli bir satırla veya totals öğesini sayfadaki belirli bir sütunla ilişkilendirebilirsiniz. Etiketler, bir e-tablonun bölümlerini, üçüncü taraf araç veya veritabanındaki alanlara anlamsal olarak bağlamak için kullanılabilir. Böylece e-tabloda yapılacak değişiklikler, uygulamanızı bozmaz.
Özellik olarak meta veri
Anahtar, konum ve değer belirterek oluşturulan meta veriler, sayfada bu konumla ilişkilendirilmiş anahtar/değer çifti olarak görev yapar. Örneğin, şunları ilişkilendirebilirsiniz:
- Satır ile
formResponseId = resp123 - Sütun içeren
lastUpdated = 1477369882.
Bu, bir e-tabloda belirli alanlar veya verilerle ilişkili özel adlandırılmış mülklerde depolamanıza ve bunlara erişmenize olanak tanır.
Proje ve belgenin görünür meta verileri
Bir geliştirici projesinin diğerinin meta verilerine müdahale etmesini önlemek için 2 meta veri visibility ayarı vardır: project ve document. E-Tablolar API'si kullanıldığında proje meta verileri yalnızca meta verileri oluşturan geliştirici projesinden görülebilir ve erişilebilir. Belge meta verilerine, belgeye erişimi olan tüm geliştirici projelerinden erişilebilir.
Açıkça bir görünürlük döndüren doküman meta verileri ve istekte bulunan geliştirici projesi için eşleşen proje meta verileri belirtmeyen sorgular.
Benzersizlik
Meta veri anahtarlarının benzersiz olması gerekmez ancak metadataId farklı olmalıdır. Meta veri oluşturur ve kimlik alanını belirtmeden bırakırsanız API, meta veri atar. Bu kimlik meta verileri tanımlamak için kullanılabilir. Anahtarlar ve diğer özellikler ise meta veri gruplarını 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 ile bir createDeveloperMetadataRequest sağlayın. İsteğe bağlı olarak metadataValue veya açık bir metadataId belirtebilirsiniz.
Halihazırda kullanımda olan bir kimlik belirtirseniz istek başarısız olur. Bir kimlik sağlamazsanız API tarafından bir kimlik atanır.
Örnek göster
Bu örnekte, istekte bir anahtar, değer ve satır sağlıyoruz. Yanıt, bu geliştirici meta veri değerlerini ve 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
Farklı tek bir geliştirici meta verisi almak için spreadsheets.developerMetadata.get yöntemini kullanın. Bu yöntemde, meta verileri içeren spreadsheetId ve geliştirici meta verilerinin benzersiz metadataId belirtilir.
Ö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 çok meta veri öğesini okuma
Birden çok 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 özellik kombinasyonlarındaki mevcut meta verilerle eşleşen bir DataFilter belirtmeniz gerekir.
Örnek göster
Bu örnekte, istekte birden çok 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ını sağlıyoruz. Yanıt, bu geliştirici meta veri değerlerini ve güncellenmiş meta veri anahtarını döndürü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 veriyi sil
Geliştirici meta verilerini silmek için batchUpdate yöntemini kullanın ve bir DeleteDeveloperMetadataRequest sağlayın.
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 kimliğine sahip geliştirici meta verisi yok404: Not Found
İ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 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 alabilir ve güncelleyebilirsiniz. Bunu yapmak için eşleşen bir DataFilter ile aşağıdaki uygun yöntemi kullanın.
Hücre değerlerini meta verilere göre 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.
Örnek göster
Bu örnekte, istekte meta veri kimliğini sağlıyoruz. Yanıt, meta veri kimliği için 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
}
}
]
}
]
}
Meta veriye göre e-tablo al
Bir e-tablo 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, normal bir "e-tablo GET" isteği olarak çalışır. Tek fark, belirtilen veri filtreleriyle eşleşen meta veri listesinin hangi sayfaların, ızgara verilerinin ve meta verilere sahip diğer nesne kaynaklarının döndürüleceğini belirler. includeGridData true (doğru) değerine ayarlanırsa, belirtilen ızgara aralıklarıyla kesişen ızgara verileri de sayfa için döndürülür.
Örnek göster
Bu örnekte, meta veri kimliğini sağlayıp istekte includeGridData öğesini 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. Meta verilerle eşleşen e-tablo kimliğini (valueInputOption) ve bir veya daha fazla DataFilterValueRange belirtmeniz gerekir.
Örnek göster
Bu örnekte, istekteki meta veri kimliğini ve güncellenmiş satır değerlerini sağlıyoruz. Yanıt, hem güncellenmiş özellikleri hem de meta veri kimliği için 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"
]
]
}
}
]
}
Değerleri meta verilere göre temizle
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 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 2 bileşenden oluşur:
| Öğe | Depolama alanı sınırı ayırma |
|---|---|
| E-tablo | 30.000 karakter |
| Bir e-tablodaki her sayfa | 30.000 karakter |
E-tablo için en fazla 30.000 karakter depolayabilirsiniz. Buna ek olarak, bir e-tablodaki her sayfa için 30.000 karakter (birinci sayfa için 30.000, 2. sayfa için 30.000 karakter vb.) depolayabilirsiniz. Yani 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.