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.
Meta veriler hakkında
Aşağıda, E-Tablolar API'si ile çalışırken göz önünde bulundurmanız gereken meta verilerle ilgili bazı önemli noktalar 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 etikettir. Örneğin,
headerRowöğesini bir sayfadaki belirli bir satırla veyatotalsöğesini belirli bir sütunla ilişkilendirebilirsiniz. Etiketler, 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ırla- Sütunlu
lastUpdated = 1477369882
Bu özellik sayesinde, 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
visibilityayarı vardır:projectvedocument. E-Tablolar API'si kullanılırkenprojectmeta verileri yalnızca bunları oluşturan Google Cloud projesinden görülebilir ve erişilebilir.documentmeta verilerine, belgeye erişimi olan herhangi bir Google Cloud projesinden erişilebilir.visibilitydeğerini açıkça belirtmeyen sorgular, isteği gönderen Google Cloud projesi için eşleşendocumentmeta verilerini ve eşleşenprojectmeta 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.API istekleri aracılığıyla meta verileri döndürme:
DataFilternesnesi, bir API isteğinden seçilecek veya döndürülecek verileri açıklayan bir API çağrısının parçasıdır.Tek bir
DataFilternesnesi, verileri bulmak için yalnızca bir tür filtre ölçütü belirtebilir:developerMetadataLookup: Belirtilen geliştirici meta verileriyle ilişkili ve ölçütlere uyan verileri seçer.a1Range: Belirtilen A1 notasyon aralığıyla eşleşen verileri seçer. Örneğin,Sheet1!A1:B10.gridRange: Sıfır tabanlı dizinleri kullanarak belirtilen ızgara aralığıyla eşleşen verileri seçer. Örneğin,Sheet1!A3:B4 == sheetId: 123456, startRowIndex: 2, endRowIndex: 4, startColumnIndex: 0, endColumnIndex: 2.
Birden fazla konum veya ölçüt arasında filtreleme yapmak için tek bir API isteğinde birden fazla
DataFilternesnesi kullanabilirsiniz.spreadsheets.values.batchGetByDataFilteryöntemi gibi bir toplu isteğeDataFilternesnelerinin dizisini veya listesini sağlayın. İstekteki veri filtrelerinden herhangi biriyle eşleşen tüm aralıklar döndürülür veya değiştirilir.Daha fazla bilgi için Meta verilerle ilişkili değerleri okuma ve yazma başlıklı makaleye bakın.
Kullanım alanları
Meta verileri yönetmeyle ilgili bazı örnek kullanım alanları aşağıda verilmiştir:
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ütunda 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. Geliştirici meta verileri, isteğe bağlı verileri bir e-tablonun çeşitli bölümleriyle ilişkilendirmek için kullanılabilir. E-tablo düzenlenirken meta veriler bu konumlarda ilişkilendirilmiş olarak kalır.
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ı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": 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 spreadsheets.developerMetadata.get yöntemini kullanın. Meta verileri içeren spreadsheetId ve geliştirici meta verilerinin benzersiz metadataId değerini belirtin.
İ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ğlanmaktadır. Yanıtta, bu geliştirici meta verileri değerlerinin yanı sıra güncellenmiş meta veri anahtarı da 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 "spreadsheet GET" isteği gibi çalışır. includeGridData
true olarak ayarlanırsa belirtilen ızgara aralıklarıyla kesişen ızgara verileri de
sayfa için döndürülür. İstek içinde field
mask 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, 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": 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
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": 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ık 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.
İlgili konular
- Google E-Tablolar verilerinize filtre uygulama
- Filtrelerle veri görünürlüğünü yönetme
- Kullanım sınırları