الكتابة الأساسية

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

يُرجى العِلم أنّه من الممكن أيضًا كتابة قيم الخلايا باستخدام الـ spreadsheet.batchUpdate التي يمكن أن تكون مفيدة إذا أردت تعديل تنسيق الخلايا أو الخصائص الأخرى في الوقت نفسه والتي لا يؤثر فيها مصدر الـ spreadsheets.values. على سبيل المثال، إذا أردت نسخ نطاق من الخلايا من ورقة بيانات إلى أخرى مع استبدال كلّ من صيغة الخلية وتنسيقها، يمكنك استخدام طريقة UpdateCellsRequest مع spreadsheet.batchUpdate.

ومع ذلك، من الأسهل استخدام طريقة spreadsheets.values.update أو طريقة spreadsheets.values.batchUpdate.

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

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

كتابة نطاق واحد

بدءًا بجدول بيانات جديد وفارغ، يعرض نموذج عينة التعليمات البرمجية التالي spreadsheets.values.update كيفية كتابة القيم في نطاق. مَعلمة طلب البحث ValueInputOption مطلوبة وتحدّد ما إذا كان سيتم تحليل القيم المكتوبة (على سبيل المثال، ما إذا كان سيتم تحويل السلسلة إلى تاريخ أم لا).

نص الطلب هو كائن ValueRange يصف قيم النطاق التي سيتم كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم من القيم منظَّمة حسب الصفوف. يتم استبدال القيم الحالية في النطاق المستهدَف.

يظهر أدناه بروتوكول الطلب.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

تتألف الاستجابة من UpdateValuesResponse كائن، مثل هذا الكائن:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

تبدو الورقة الناتجة على النحو التالي:

الكتابة بشكل انتقائي في نطاق

عند كتابة القيم في نطاق، من الممكن تجنُّب تغيير بعض الخلايا الحالية من خلال ضبط عناصر المصفوفة المقابلة على null. من الممكن أيضًا محو خلية من خلال كتابة سلسلة فارغة ("") فيها.

بدءًا بورقة بيانات تحتوي على البيانات نفسها التي تم إنتاجها في المثال أعلاه، يعرض عينة تعليمات برمجية التالي spreadsheets.values.update كيفية كتابة القيم في النطاق B1:D4، مع ترك بعض الخلايا بدون تغيير ومحو خلايا أخرى بشكل انتقائي. مَعلمة طلب البحث ValueInputOption مطلوبة وتحدّد ما إذا كان سيتم تحليل القيم المكتوبة (على سبيل المثال، ما إذا كان سيتم تحويل السلسلة إلى تاريخ أم لا).

نص الطلب هو كائن ValueRange يصف قيم النطاق التي سيتم كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم من القيم منظَّمة حسب الأعمدة.

يظهر أدناه بروتوكول الطلب.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

يسرد الحقل values هنا التغييرات التي تم إجراؤها على كل عمود في النطاق. تشير المصفوفة الأولى إلى أنّه سيتم ترك الخلية B1 بدون تغيير (بسبب عنصر المصفوفة null)، بينما سيتم محو الخلية B4 (سلسلة فارغة). تم تعديل قيمتَي الخليتين B2 وB3. تُجري المصفوفة الثالثة العمليات نفسها على العمود D، بينما تشير المصفوفة الفارغة الثانية إلى أنّه سيتم ترك العمود C بدون تغيير.

تتألف الاستجابة من كائن UpdateValuesResponse مثل هذا الكائن:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

تبدو الورقة الناتجة على النحو التالي:

يُرجى العِلم أنّ صف "المجاميع"، على الرغم من أنّه لم يتم تغييره مباشرةً من خلال هذا الطلب، يتغيّر لأنّ خلاياه تحتوي على صيغ تعتمد على الخلايا المعدَّلة.

الكتابة في نطاقات متعددة

بدءًا بورقة فارغة، يعرض نموذج عينة التعليمات البرمجية التالي spreadsheets.values.batchUpdate كيفية كتابة القيم في النطاقَين Sheet1!A1:A4 و Sheet1!B1:D2. يتم استبدال القيم الحالية في النطاق المستهدَف. يتألف نص الطلب من كائن ValueInputOptionيوضّح كيفية تفسير بيانات الإدخال ومصفوفة من ValueRange كائنات تتوافق مع كل نطاق مكتوب. يحدّد الحقل majorDimension ما إذا كان سيتم تفسير المصفوفات المضمَّنة على أنّها مصفوفات أعمدة أو صفوف.

يظهر أدناه بروتوكول الطلب.

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

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

تتألف الاستجابة من كائن يسرد إحصاءات الخلايا المعدَّلة ومصفوفة من UpdateValuesResponse الكائنات، واحد لكل نطاق معدَّل. على سبيل المثال:

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

تبدو الورقة الناتجة على النحو التالي:

كتابة القيم بدون تحليلها

بدءًا بورقة بيانات فارغة، تعرض عينة التعليمات البرمجية التالية spreadsheets.values.update كيفية كتابة القيم في النطاق Sheet1!A1:E1، ولكنّه يستخدم معلمات طلب البحث RAW ValueInputOption لمنع تحليل السلاسل المكتوبة على أنّها صيغ أو قيم منطقية أو أرقام. تظهر هذه القيم كسلاسل ويتم ضبط النص في ورقة البيانات.

نص الطلب هو كائن ValueRange يصف قيم النطاق التي سيتم كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم من القيم منظَّمة حسب الصفوف. يتم استبدال القيم الحالية في النطاق المستهدَف.

يظهر أدناه بروتوكول الطلب.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

تتألف الاستجابة من كائن UpdateValuesResponse مثل هذا الكائن:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

تبدو الورقة الناتجة على النحو التالي:

يُرجى العِلم أنّ "صواب" في المنتصف وهي قيمة منطقية، بينما "123.45" في أقصى اليسار لأنّها رقم، و"10" في أقصى اليمين لأنّها سلسلة. لا يتم تحليل الصيغة، وتظهر أيضًا كسلسلة.

إضافة القيم

ابدأ بورقة بيانات مثل الجدول أدناه:

يعرض نموذج الرمز البرمجي التالي spreadsheets.values.append كيفية إضافة صفَين جديدَين من القيم بدءًا من الصف 3. مَعلمة طلب البحث ValueInputOption مطلوبة وتحدّد ما إذا كان سيتم تحليل القيم المكتوبة (على سبيل المثال، ما إذا كان سيتم تحويل السلسلة إلى تاريخ أم لا).

نص الطلب هو كائن ValueRange يصف قيم النطاق التي سيتم كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم من القيم منظَّمة حسب الصفوف.

يظهر أدناه بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

تتألف الاستجابة من AppendValuesResponse كائن مثل هذا الكائن:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

تبدو الورقة الناتجة على النحو التالي: