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