تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

تتيح لك بيانات المطوِّر إجراء عمليات مثل:

ربط بيانات عشوائية بعناصر ومواقع مختلفة في جدول بيانات: على سبيل المثال، ربط 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 ضمن هذا الحدّ.

قراءة البيانات الوصفية للمطوّرين وكتابتها تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

لمحة عن بيانات المطوّرين الوصفية

البيانات الوصفية كعلامات

البيانات الوصفية كسمات

البيانات الوصفية المرئية على مستوى المشروع مقارنةً بالبيانات الوصفية المرئية على مستوى المستند

التفرّد

إنشاء بيانات وصفية

قراءة عنصر بيانات وصفية واحد

قراءة عناصر بيانات وصفية متعددة

تعديل البيانات الوصفية

حذف البيانات الوصفية

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

الحصول على قيم الخلايا حسب البيانات الوصفية

الحصول على جدول بيانات حسب البيانات الوصفية

تعديل القيم حسب البيانات الوصفية

محو القيم حسب البيانات الوصفية

حدود مساحة تخزين البيانات الوصفية

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