عمليات البيانات

تتيح لك Google Sheets API معالجة البيانات داخل جداول البيانات بطرق مختلفة. معظم الوظائف المتوفرة للمستخدمين الذين يستخدمون واجهة مستخدم جداول البيانات من الممكن القيام بها أيضًا باستخدام Sheets API. توضح الأمثلة في هذه الصفحة كيف يمكنك تحقيق بعض عمليات جداول البيانات الشائعة باستخدام Sheets API.

يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون محايدة اللغة. لمعرفة كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات برامج واجهة Google API، يمكنك الاطّلاع على مقالة تحديث جداول البيانات.

في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى مكان تقديم هذين المعرّفَين. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL لجدول البيانات. يمكنك الحصول على معرّف ورقة البيانات باستخدام الطريقة spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. مثال على النطاق Sheet1!A1:D5.

تطبيق التحقق من صحة البيانات على نطاق

يوضح نموذج الرمز البرمجي spreadsheets.batchUpdate التالي كيفية استخدام SetDataValidationRequest لتطبيق قاعدة التحقّق من صحة البيانات، حيث تكون "القيمة > 5"، على كل خلية في النطاق A1:D10.

في ما يلي بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "setDataValidation": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "rule": {
          "condition": {
            "type": "NUMBER_GREATER",
            "values": [
              {
                "userEnteredValue": "5"
              }
            ]
          },
          "inputMessage": "Value must be > 5",
          "strict": true
        }
      }
    }
  ]
}

نسخ تنسيق الخلية ولصقه

يوضّح نموذج الرمز البرمجي spreadsheets.batchUpdate التالي كيفية استخدام CopyPasteRequest لنسخ التنسيق فقط في النطاق A1:D10 ولصقه في النطاق F1:I10 في ورقة البيانات نفسها. تستخدم الطريقة التعداد PasteType مع PASTE_FORMAT للصق التنسيق والتحقق من صحة البيانات فقط. تظل القيم الأصلية في A1:D10 بدون تغيير.

في ما يلي بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "copyPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 5,
          "endColumnIndex": 9
        },
        "pasteType": "PASTE_FORMAT",
        "pasteOrientation": "NORMAL"
      }
    }
  ]
}

قص الخلايا ولصقها

يوضّح نموذج الرمز البرمجي spreadsheets.batchUpdate التالي كيفية استخدام CutPasteRequest. تخفض النطاق A1:D10 وتستخدم التعداد PasteType مع PASTE_NORMAL للصق القيم والمعادلات وتنسيقها ودمجها في النطاق F1:I10 في ورقة البيانات نفسها. تتم إزالة محتويات خلية النطاق المصدر الأصلي.

في ما يلي بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "cutPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "rowIndex": 0,
          "columnIndex": 5
        },
        "pasteType": "PASTE_NORMAL"
      }
    }
  ]
}

تكرار صيغة على نطاق

يوضح نموذج الرمز البرمجي spreadsheets.batchUpdate التالي كيفية استخدام RepeatCellRequest لنسخ الصيغة =FLOOR(A1*PI()) إلى النطاق B1:D10. يزداد نطاق المعادلة تلقائيًا لكل صف وعمود في النطاق، بدءًا من الخلية اليسرى العلوية. على سبيل المثال، تحتوي الخلية B1 على المعادلة =FLOOR(A1*PI())، بينما تحتوي الخلية D6 على المعادلة =FLOOR(C6*PI()).

في ما يلي بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 1,
          "endColumnIndex": 4
        },
        "cell": {
          "userEnteredValue": {
              "formulaValue": "=FLOOR(A1*PI())"
          }
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

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

يوضح نموذج الرمز البرمجي spreadsheets.batchUpdate التالي كيفية استخدام SortRangeRequest لترتيب النطاق A1:D10 أولاً حسب العمود B بترتيب تصاعدي، ثم حسب العمود C بترتيب تنازلي، ثم حسب العمود D بترتيب تنازلي.

في ما يلي بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "sortRange": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "sortSpecs": [
          {
            "dimensionIndex": 1,
            "sortOrder": "ASCENDING"
          },
          {
            "dimensionIndex": 2,
            "sortOrder": "DESCENDING"
          },
          {
            "dimensionIndex": 3,
            "sortOrder": "DESCENDING"
          }
        ]
      }
    }
  ]
}