Geliştirici meta verileri ö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.
Geliştirici üst verileri, aşağıdakiler gibi işlemleri yapmanıza olanak tanır:
E-tablodaki çeşitli öğeler ve konumlarla rastgele verileri ilişkilendirme: Örneğin,
totalsile D sütununu veyaresponseId = 1234ile 7. satırı 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ı veyaresponseIdanahtarı verildiğ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 gösterimi aracılığıyla 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 geliştirici meta verilerine erişim sağlar.
Geliştirici meta verileri hakkında
Bu bölümde, Sheets API ile çalışırken göz önünde bulundurmanız gereken geliştirici meta verilerinin bazı önemli yönleri açıklanmaktadır.
Etiket olarak meta veriler
Geliştirici meta verilerinin bir kullanım alanı, yalnızca bir anahtar ve konum kullanılarak e-tablodaki bir konumu adlandıran etikettir. Örneğin, headerRow öğesini bir sayfadaki belirli bir satırla veya totals öğesini 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ı bozmaz.
Ö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ırlalastUpdated = 1477369882ile bir sütun.
Bu özellik sayesinde, bir e-tablodaki belirli alanlar veya verilerle ilişkili özel adlandırılmış özellikleri saklayabilir ve bunlara erişebilirsiniz.
Proje ve doküman düzeyinde görünür meta veriler
Bir geliştirici projesinin başka bir projenin meta verilerine müdahale etmesini önlemek için 2 meta veri visibility ayarı vardır: project ve document. Sheets API kullanılırken proje meta verileri yalnızca bunları oluşturan geliştirici projesinden görülebilir ve erişilebilir. Doküman meta verilerine, dokümana erişimi olan herhangi bir geliştirici projesinden erişilebilir.
Görünürlüğü açıkça belirtmeyen sorgular, isteği gönderen geliştirici projesi için eşleşen belge meta verilerini ve eşleşen proje meta verilerini döndürür.
Benzersizlik
Meta veri anahtarlarının benzersiz olması gerekmez ancak metadataId farklı 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 batchUpdate yöntemini kullanın ve metadataKey, location ve visibility ile bir createDeveloperMetadataRequest sağlayın. İsteğe bağlı olarak bir metadataValue veya açık bir metadataId belirtebilirsiniz.
Zaten kullanımda 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": 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 verisini 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 değerini belirtin.
İstek
Bu örnekte, e-tablo kimliğini ve meta veri kimliğini istekte sağlıyoruz. Yanıt, meta veri kimliğinin geliştirici meta verisi 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 öğ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": 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 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.
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": 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 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. "metadataId 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": 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 alıp güncelleyebilirsiniz. Bunu yapmak için aşağıdaki uygun yöntemi 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ış) 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 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 "spreadsheet 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.
Bu örnekte, meta veri kimliğini sağlıyor ve istekte includeGridData'yı false olarak ayarlıyoruz. 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.
Bu örnekte, istekte meta veri kimliğini ve güncellenen satır değerlerini sağlıyoruz. Yanıtta hem güncellenen özellikler hem de meta veri kimliğinin verileri döndürülü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.
İ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": 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. Bu sınır karakter cinsinden ölçülür ve 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-tablo için 30.000 karaktere kadar depolama alanı kullanabilirsiniz. Ayrıca, bir e-tablodaki her sayfa için 30.000 karakter depolayabilirsiniz (1. sayfa için 30.000, 2. sayfa için 30.000 vb.). Bu nedenle,3 sayfalık bir e-tablo en fazla 120.000 karakterlik geliştirici meta verisi içerebilir.
developerMetadata nesnesinin anahtar ve değer özelliklerindeki her karakter bu sınıra dahil edilir.