تتيح لك ميزة البيانات الوصفية للمطوّر ربط البيانات الوصفية بجهات ومقاصد مختلفة في جدول بيانات. يمكنك بعد ذلك طلب هذه البيانات الوصفية واستخدامها للعثور على العناصر المرتبطة بها.
يمكنك ربط البيانات الوصفية بالصفوف أو الأعمدة أو أوراق البيانات أو جدول البيانات.
تتيح لك البيانات الوصفية للمطوّرين تنفيذ عمليات مثل:
ربط بيانات عشوائية بجهات ومواقع جغرافية مختلفة في جدول ملف شخصي على Google: على سبيل المثال، ربط
totalsبالعمود D، أوresponseId = 1234بالصف 7العثور على جميع المواقع الجغرافية والبيانات المرتبطة بمفتاح أوسمة وصفية معيّن أو سمة: على سبيل المثال، عند توفّر المفتاح
totalsالمرتبط بالعمود D أوresponseId، يمكنك عرض جميع الصفوف التي تحتوي على البيانات الوصفيةresponseIdوقيمة البيانات الوصفية المرتبطة بها.العثور على جميع البيانات المرتبطة بكيان أو موقع جغرافي معيّن: على سبيل المثال، في العمود "د"، عرض جميع البيانات الوصفية المرتبطة بهذا الموقع الجغرافي
استرداد القيم في موقع معيّن من خلال تحديد البيانات الوصفية المرتبطة: على سبيل المثال، عند استخدام
totals، يتم عرض تمثيل للقيم المضمّنة في العمود أو الصف المرتبط، أو عند استخدامsummary، يتم عرض تمثيل لمصدر "الجدول الزمني" المرتبط.تعديل القيم في موقع معيّن من خلال تحديد البيانات الوصفية المرتبطة: على سبيل المثال، بدلاً من تعديل القيم في صف من خلال ترميز A1، يمكنك تعديل القيم من خلال الإشارة إلى رقم تعريف البيانات الوصفية.
قراءة البيانات الوصفية وكتابتها
يوفر المورد spreadsheets.developerMetadata إمكانية الوصول إلى البيانات الوصفية للمطوّر المرتبطة بموقع جغرافي أو عنصر في جدول بيانات.
لمحة عن البيانات الوصفية للمطوّر
يوضِّح هذا القسم بعض الجوانب الرئيسية لبيانات التعريف الخاصة بالمطوّرين التي يجب مراعاتها عند العمل مع Sheets API.
البيانات الوصفية كعلامات
من بين استخدامات البيانات الوصفية للمطوّر هي العلامة التي تحدّد اسم موقع جغرافي في جدول البيانات باستخدام مفتاح وموقع جغرافي فقط. على سبيل المثال، يمكنك ربط headerRow بصف معيّن أو totals بأحد الأعمدة في ورقة البيانات. يمكن استخدام العلامات لربط أجزاء من جدول ข้อมูล بصريًا بالحقول في أداة أو قاعدة بيانات تابعة لجهة خارجية، وبالتالي لن تؤدي التغييرات في جدول البيانات إلى تعطيل تطبيقك.
البيانات الوصفية بصفتها خصائص
تعمل البيانات الوصفية التي تم إنشاؤها من خلال تحديد مفتاح وموقع وقيمة كأحد أزواج المفتاح/القيمة المرتبطة بهذا الموقع في ورقة البيانات. على سبيل المثال، يمكنك ربط ما يلي:
formResponseId = resp123مع صفlastUpdated = 1477369882مع عمود
تتيح لك هذه الميزة تخزين السمات المُسمّاة المخصّصة والوصول إليها والمرتبطة بمناطق أو بيانات معيّنة في جدول بيانات.
البيانات الوصفية الظاهرة للمشروع مقارنةً بالبيانات الوصفية للوثيقة
لمنع مشروع مطوّر من التدخل في البيانات الوصفية لمشروع آخر، هناك
إعدادان للبيانات الوصفية visibility: project وdocument. باستخدام واجهة برمجة التطبيقات Sheets API،
لا تظهر البيانات الوصفية للمشروع ولا يمكن الوصول إليها إلا من مشروع المطوّر الذي
أنشأها. يمكن الوصول إلى البيانات الوصفية للمستند من أي مشروع للمطوّر لديه
إذن الوصول إلى المستند.
إنّ طلبات البحث التي لا تحدّد بشكل صريح مستوى الوصول تعرض بيانات وصفية مطابقة للمستندات وبيانات وصفية مطابقة للمشروع المتعلّق بملف المشروعات الذي يقدّم الطلب.
التميز
ليس من الضروري أن تكون مفاتيح البيانات الوصفية فريدة، ولكن يجب أن يكون metadataId
مميّزًا. إذا أنشأت بيانات وصفية وتركت حقل رقم التعريف غير محدّد، سيحدّد واجهة برمجة التطبيقات رقم تعريف. يمكن استخدام هذا المعرّف لتحديد
البيانات الوصفية، في حين يمكن استخدام المفاتيح والسمات الأخرى لتحديد مجموعات
البيانات الوصفية.
إنشاء بيانات وصفية
لإنشاء بيانات وصفية، استخدِم الأسلوب
batchUpdate
، وقدِّم metadataKey وlocation وvisibility في createDeveloperMetadataRequest. يمكنك اختياريًا
تحديد 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 حرف في جدول البيانات. بالإضافة إلى ذلك، يمكنك تخزين 30,000 حرف لكل ورقة ضمن جدول بيانات (30,000 للورقة الأولى و30,000 للورقة 2 وما إلى ذلك). وبالتالي، يمكن أن يحتوي جدول بيانات يتضمّن 3 صفحات على ما يصل إلى 120,000 حرف من البيانات الوصفية للمطوّر.
يتم احتساب كل حرف في سمتَي المفتاح والقيمة لكائن developerMetadata
ضِمن هذا الحدّ الأقصى.