تتيح لك ميزة البيانات الوصفية للمطوّر ربط البيانات الوصفية بكيانات ومواقع جغرافية مختلفة في جدول بيانات. يمكنك بعد ذلك الاستعلام عن بيانات التعريف هذه واستخدامها للعثور على الكائنات التي ترتبط بها.
يمكنك ربط البيانات الوصفية بالصفوف أو الأعمدة أو الأوراق أو جدول البيانات.
تتيح لك البيانات الوصفية للمطوِّر إجراء عمليات مثل:
ربط البيانات العشوائية بكيانات ومواقع جغرافية مختلفة في جدول بيانات: على سبيل المثال، يمكنك ربط
totalsبالعمود D أوresponseId = 1234بالصف 7.البحث عن جميع المواقع الجغرافية والبيانات المرتبطة بمفتاح أو سمة بيانات وصفية معيّنة: على سبيل المثال، بناءً على المفتاح
totalsالمرتبط بالعمود D أو تحديدresponseId، يمكنك عرض جميع الصفوف التي تتضمّن بياناتresponseIdالوصفية وقيمة البيانات الوصفية المرتبطة بها.البحث عن جميع البيانات المرتبطة بجهة معيّنة أو موقع جغرافي معيّن: على سبيل المثال، في العمود D، اعرض جميع البيانات الوصفية المرتبطة بهذا الموقع الجغرافي.
استرداد القيم في موقع جغرافي من خلال تحديد البيانات الوصفية المرتبطة: على سبيل المثال، إذا كانت السمة
totalsتعرض تمثيل القيم الواردة في العمود أو الصف المرتبط بها، أو يتم إعطاءsummaryتمثيلاً لمورد ورقة البيانات المرتبط.تعديل القيم في موقع جغرافي من خلال تحديد البيانات الوصفية ذات الصلة: على سبيل المثال، بدلاً من تعديل القيم في صف من خلال ترميز A1، يمكنك تعديل القيم من خلال الإشارة إلى رقم تعريف البيانات الوصفية.
قراءة البيانات الوصفية وكتابتها
يوفر مورد spreadsheets.developerMetadata إمكانية الوصول إلى البيانات الوصفية لمطوّر البرامج المرتبطة بموقع أو عنصر في جدول بيانات.
لمحة عن البيانات الوصفية للمطوّرين
يصف هذا القسم بعض الجوانب الرئيسية للبيانات الوصفية للمطوّرين التي يجب مراعاتها عند العمل باستخدام Sheets API.
البيانات الوصفية كعلامات
تتمثل إحدى استخدامات البيانات الوصفية للمطوِّرين في علامة تحدِّد موقعًا جغرافيًا في
جدول البيانات باستخدام مفتاح وموقع فقط. على سبيل المثال، يمكنك ربط headerRow بصف معيّن أو totals بعمود معيّن داخل ورقة. يمكن استخدام العلامات لربط أجزاء من جدول البيانات دلاليًا بالحقول في أداة أو قاعدة بيانات تابعة لجهة خارجية، لذا لن تؤدي التغييرات في جدول البيانات إلى تعطّل تطبيقك.
البيانات الوصفية كمواقع
تعمل بيانات التعريف التي يتم إنشاؤها من خلال تحديد مفتاح وموقع وقيمة كزوج المفتاح/القيمة المرتبط بهذا الموقع في ورقة. على سبيل المثال، يمكنك ربط:
formResponseId = resp123مع صفlastUpdated = 1477369882يحتوي على عمود.
يتيح لك هذا إمكانية تخزين والوصول إلى خصائص مسماة مخصصة مرتبطة بمناطق أو بيانات معينة في جدول بيانات.
البيانات الوصفية المرئية للمشروع مقابل الوثيقة
لمنع مشروع أحد المطوّرين من التداخل مع البيانات الوصفية لمشروع آخر، هناك إعدادان للبيانات الوصفية فيهما visibility، وهما project وdocument. باستخدام Sheets API، لا تكون بيانات التعريف للمشروع
مرئية ويمكن الوصول إليها إلا من مشروع المطور
الذي أنشأه. يمكن الوصول إلى بيانات التعريف للمستند من أي مشروع
مطور لديه إمكانية الوصول إلى الوثيقة.
إنّ طلبات البحث التي لا تحدّد بشكل صريح مستوى ظهور تعرض البيانات الوصفية للمستند المطابِق والبيانات الوصفية المطابقة للمشروع في مشروع المطوّر الذي يقدّم الطلب.
التميز
ليس من الضروري أن تكون مفاتيح البيانات الوصفية فريدة، ولكن يجب أن تكون مفاتيح metadataId مختلفة. إذا أنشأت بيانات وصفية وتركت حقل رقم التعريف غير محدد،
فستعين واجهة برمجة التطبيقات حقلاً. ويمكن استخدام هذا المعرف لتحديد بيانات التعريف، بينما يمكن استخدام المفاتيح والسمات الأخرى لتحديد مجموعات من
البيانات الوصفية.
إنشاء البيانات الوصفية
لإنشاء بيانات وصفية، استخدِم طريقة
batchUpdate
وقدِّم السمة createDeveloperMetadataRequest إلى metadataKey وlocation وvisibility. ويمكنك تحديد metadataValue أو metadataId صريح اختياريًا.
وإذا حدّدت معرّفًا قيد الاستخدام، لن ينجح الطلب. إذا لم توفّر معرّفًا، تعيّن واجهة برمجة التطبيقات معرّفًا
عرض مثال
في هذا المثال، نقدّم مفتاحًا وقيمة ووصفًا في الطلب. يعرض الردّ قيم البيانات الوصفية الخاصة بمطوّري البرامج هذه، بالإضافة إلى رقم تعريف البيانات الوصفية الذي تم تخصيصه.
الطلب
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}
الرد
{
"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"
}
}
}
]
}
قراءة عنصر واحد من البيانات الوصفية
لاسترداد بيانات وصفية واحدة ومميزة لمطوّر البرامج، استخدِم طريقة
spreadsheets.developerMetadata.get، مع تحديد spreadsheetId التي تحتوي على البيانات الوصفية وmetadataId الفريدة للسمة الوصفية الخاصة بمطوّر البرامج.
عرض مثال
الطلب
في هذا المثال، نقدّم رقم تعريف جدول البيانات ورقم تعريف البيانات الوصفية في الطلب. ويعرض الردّ قيم البيانات الوصفية لمطوّر البرامج لرقم تعريف البيانات الوصفية.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
الرد
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
قراءة عناصر بيانات وصفية متعددة
لاسترداد عناصر متعددة من البيانات الوصفية للمطوّرين، استخدِم طريقة spreadsheets.developerMetadata.search. عليك تحديد DataFilter تتطابق مع أي بيانات وصفية حالية في أي مجموعة من السمات، مثل المفتاح أو القيمة أو الموقع الجغرافي أو مستوى الظهور.
عرض مثال
في هذا المثال، نقدّم العديد من معرّفات البيانات الوصفية في الطلب. ويعرض الرد قيم البيانات الوصفية لمطوّر البرامج لكل رقم تعريف بيانات وصفية.
الطلب
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
الرد
{
"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
}
}
]
}
]
}
تعديل البيانات الوصفية
لتعديل البيانات الوصفية للمطوّرين، استخدِم طريقة
spreadsheets.batchUpdate
وأدخِل القيمة
UpdateDeveloperMetadataRequest.
ستحتاج إلى تحديد DataFilter يستهدف البيانات الوصفية المراد تعديلها وكائن DeveloperMetadata بالقيم الجديدة وقناع حقل يصف الحقول المراد تعديلها.
عرض مثال
في هذا المثال، نقدّم رقم تعريف البيانات الوصفية ورقم تعريف ورقة البيانات ومفتاح بيانات وصفية جديد في الطلب. وسيعرض الرد قيم البيانات الوصفية هذه الخاصة بالمطوِّرين، بالإضافة إلى مفتاح البيانات الوصفية المعدَّل.
الطلب
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}
الرد
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
حذف البيانات الوصفية
لحذف البيانات الوصفية للمطوّرين، استخدِم الإجراء
batchUpdate
وقدّم DeleteDeveloperMetadataRequest.
وعليك تحديد السمة DataFilter لاختيار البيانات الوصفية التي تريد حذفها.
عرض مثال
في هذا المثال، نقدّم رقم تعريف البيانات الوصفية في الطلب. ويعرض الردّ قيم البيانات الوصفية لمطوّر البرامج لرقم تعريف البيانات الوصفية.
للتأكد من إزالة البيانات الوصفية للمطوِّرين، استخدِم طريقة spreadsheets.developerMetadata.get، مع تحديد رقم تعريف البيانات الوصفية الذي تم حذفه. من المفترَض أن تتلقّى استجابة رمز حالة HTTP 404: Not Found، مع رسالة تفيد بأنّه "ما مِن بيانات وصفية لمطوّر البرامج برقم التعريف metadataId.
الطلب
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}
الرد
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
قراءة وكتابة القيم المرتبطة بالبيانات الوصفية
يمكنك أيضًا استرداد قيم الخلايا في الصفوف والأعمدة وتحديثها من خلال تحديد بيانات التعريف المرتبطة بالمطوّرين والقيم التي تريد تحديثها. لإجراء ذلك، استخدِم الطريقة المناسبة أدناه مع سمة DataFilter مطابقة.
الحصول على قيم الخلايا حسب البيانات الوصفية
للحصول على قيم الخلايا حسب البيانات الوصفية، استخدِم الإجراء spreadsheets.values.batchGetByDataFilter. ستحتاج إلى تحديد رقم تعريف جدول البيانات وفلتر بيانات واحد أو أكثر يتطابق مع البيانات الوصفية.
عرض مثال
في هذا المثال، نقدّم رقم تعريف البيانات الوصفية في الطلب. ويعرض الاستجابة قيم خلايا الصفوف (رقم الطراز، المبيعات الشهرية) لمعرّف البيانات الوصفية.
الطلب
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}
الرد
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}
الحصول على جدول البيانات حسب البيانات الوصفية
عند استرداد جدول بيانات، يمكنك عرض مجموعة فرعية من البيانات باستخدام طريقة spreadsheets.getByDataFilter. ستحتاج إلى تحديد رقم تعريف جدول البيانات وفلتر بيانات واحد أو أكثر يتطابق مع البيانات الوصفية.
يعمل هذا الطلب كطلب عادي لـ "جدول بيانات GET" باستثناء قائمة البيانات الوصفية المطابقة لفلاتر البيانات المحددة التي تحدد الأوراق وبيانات الشبكة وموارد الكائنات الأخرى ذات البيانات الوصفية التي يتم عرضها. إذا تم ضبط includeGridData على "صحيح"، يتم أيضًا عرض بيانات الشبكة التي تتقاطع مع نطاقات الشبكة المحدّدة للورقة.
عرض مثال
في هذا المثال، نقدّم معرّف البيانات الوصفية ونضبط includeGridData على "false" في الطلب. تعرض الاستجابة كل من خصائص جدول البيانات والورقة.
الطلب
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}
الرد
{
"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
}
تعديل القيم حسب البيانات الوصفية
لتعديل قيم الخلايا التي تتطابق مع بيانات وصفية معيّنة، استخدِم الطريقة
spreadsheets.values.batchUpdateByDataFilter. عليك تحديد رقم تعريف جدول البيانات، valueInputOption، وواحدة أو أكثر من DataFilterValueRange التي تتطابق مع البيانات الوصفية.
عرض مثال
في هذا المثال، نقدّم رقم تعريف البيانات الوصفية وقيم الصفوف المعدَّلة في الطلب. يعرض الردّ كلاً من السمات والبيانات المعدَّلة لمعرّف البيانات الوصفية.
الطلب
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}
الرد
{
"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"
]
]
}
}
]
}
محو القيم حسب البيانات الوصفية
لمحو قيم الخلايا التي تطابق بيانات وصفية معيّنة، استخدِم طريقة spreadsheets.values.batchClearByDataFilter. ستحتاج إلى تحديد فلتر للبيانات لاختيار البيانات الوصفية التي تريد محوها.
عرض مثال
الطلب
في هذا المثال، نقدّم رقم تعريف البيانات الوصفية في الطلب. تعرض الاستجابة رقم تعريف جدول البيانات والنطاقات التي تم محوها.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
الرد
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}
الحدود القصوى لمساحة تخزين البيانات الوصفية
هناك حد أقصى لإجمالي بيانات البيانات الوصفية التي يمكنك تخزينها في جدول بيانات. يتم قياس هذا الحد بالأحرف ويتألف من مكوّنَين:
| المنتج/الخدمة | تخصيص الحدّ الأقصى لمساحة التخزين |
|---|---|
| جدول بيانات | 30,000 حرف |
| كل ورقة داخل جدول بيانات | 30,000 حرف |
يمكنك تخزين ما يصل إلى 30.000 حرف في جدول البيانات. بالإضافة إلى ذلك، يمكنك تخزين 30000 حرف لكل ورقة في جدول بيانات (30000 للورقة الأولى، و30000 للورقة 2، وهكذا). لذلك يمكن أن يحتوي جدول بيانات مكون من 3 صفحات على ما يصل إلى 120000 حرف من بيانات التعريف للمطور.
ويتم احتساب كل حرف في سمات المفتاح والقيمة في عنصر developerMetadata ضمن هذا الحدّ الأقصى.