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

تسمح لك 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. مثال على النطاق هو 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,
}

تظهر الورقة الناتجة على النحو التالي:

	A	B	C	D
1	المنتج/الخدمة	التكلفة	المخزون	تاريخ الشحن
2	العجلة	SAR 20.50	4	1/3/2016
3	باب	دولار هونغ كونغ	2	2016/3/15
4	المحرك	$100	1	20/3/2016
5	مجاميع	135.5 دولار نيوزيلندي	7	20/3/2016

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

عند كتابة القيم إلى نطاق، يمكن تجنُّب تغيير بعض الخلايا الحالية من خلال ضبط عناصر الصفيف المقابلة على 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,
}

تظهر الورقة الناتجة على النحو التالي:

	A	B	C	D
1	المنتج/الخدمة	التكلفة	المخزون	تاريخ الشحن
2	العجلة	1.00 دولار أمريكي (أو ما يعادله بالعملة المحلية)	4	1/4/2016
3	باب	2 دولار أميركي (أو ما يعادلهما بالعملة المحلية)	2	15/4/2016
4	المحرك		1
5	مجاميع	3.00 دولارات أمريكية (أو ما يعادلها بالعملة المحلية)	7	15/4/2016

لاحظ أن صف "Totals" (الإجماليات)، على الرغم من عدم تغييره بشكل مباشر من خلال هذا الطلب، يتغير لأن خلاياه تحتوي على صيغ تعتمد على الخلايا التي تم تغييرها.

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

بدءًا من ورقة فارغة، يوضّح نموذج الرمز البرمجي 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,
    }
  ],
}

تظهر الورقة الناتجة على النحو التالي:

	A	B	C	D
1	المنتج/الخدمة	التكلفة	المخزون	تاريخ الشحن
2	العجلة	SAR 20.50	4	1/3/2016
3	باب
4	المحرك
5

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

بدءًا من ورقة فارغة، يوضّح نموذج الرمز البرمجي 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,
}

تظهر الورقة الناتجة على النحو التالي:

	A	B	C	D	E
1	البيانات	123.45	TRUE	=MAX(D2:D4)	10
2

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

إلحاق القيم

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

	A	B	C	D
1	المنتج/الخدمة	التكلفة	المخزون	تاريخ الشحن
2	العجلة	SAR 20.50	4	1/3/2016
3

يوضح نموذج التعليمات البرمجية 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,
  }
}

تظهر الورقة الناتجة على النحو التالي:

	A	B	C	D
1	المنتج/الخدمة	التكلفة	المخزون	تاريخ الشحن
2	العجلة	SAR 20.50	4	1/3/2016
3	باب	دولار هونغ كونغ	2	2016/3/15
4	المحرك	$100	1	20/3/2016
5