قراءة البيانات الوصفية للمطوّرين وكتابتها

تتيح لك ميزة "البيانات الوصفية للمطوّرين" ربط البيانات الوصفية بمختلف الكيانات والمواقع الجغرافية في جدول بيانات. يمكنك بعد ذلك البحث في هذه البيانات الوصفية واستخدامها للعثور على العناصر المرتبطة بها.

يمكنك ربط البيانات الوصفية بالصفوف أو الأعمدة أو الأوراق أو جدول البيانات.

تتيح لك بيانات المطوّرين تنفيذ عمليات مثل:

  • ربط بيانات عشوائية بعناصر ومواقع مختلفة في جدول بيانات: على سبيل المثال، ربط totals بالعمود D أو responseId = 1234 بالصف 7

  • العثور على جميع المواقع الجغرافية والبيانات المرتبطة بمفتاح بيانات وصفية أو سمة معيّنة: على سبيل المثال، عند توفّر المفتاح totals المرتبط بالعمود D أو عند توفّر responseId، يتم عرض جميع الصفوف التي تتضمّن البيانات الوصفية responseId وقيمة البيانات الوصفية المرتبطة بها.

  • العثور على جميع البيانات المرتبطة بكيان أو موقع جغرافي معيّن: على سبيل المثال، بالنظر إلى العمود D، يمكنك عرض جميع البيانات الوصفية المرتبطة بهذا الموقع الجغرافي.

  • استرداد القيم في موقع جغرافي من خلال تحديد البيانات الوصفية المرتبطة: على سبيل المثال، عند توفّر totals، يتم عرض تمثيل للقيم الواردة في العمود أو الصف المرتبطَين، أو عند توفّر summary، يتم عرض تمثيل لمورد "جداول بيانات Google" المرتبط.

  • تعديل القيم في موقع جغرافي من خلال تحديد البيانات الوصفية المرتبطة: على سبيل المثال، بدلاً من تعديل القيم في صف من خلال ترميز 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 على "خطأ" في الطلب. تعرض الاستجابة كلاً من خصائص جدول البيانات والورقة.

الطلب

{
  "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 حرف للورقة الثانية وما إلى ذلك). وبالتالي، يمكن أن يحتوي جدول بيانات يتضمّن 3 صفحات على ما يصل إلى 120,000 حرف من البيانات الوصفية للمطوّرين.

يُحتسب كل حرف في سمات المفتاح والقيمة الخاصة بكائن developerMetadata ضمن هذا الحدّ.