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

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

لاحظ أنه من الممكن أيضًا كتابة قيم الخلايا باستخدام spreadsheet.batchUpdate والتي يمكن أن تكون مفيدة إذا كنت تريد تعديل تنسيق الخلية في آنٍ واحد أو الخصائص الأخرى التي spreadsheets.values لا يؤثر ذلك المورد. على سبيل المثال، إذا كنت تريد نسخ نطاق من الخلايا من ورقة إلى أخرى أثناء الكتابة فوق كل من معادلة الخلية والخلية والتنسيق، يمكنك استخدام UpdateCellsRequest باستخدام a 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	ب	C	D
1	المنتج/الخدمة	التكلفة	مخزن	تاريخ الشحن
2	العجلة	20.50 دولار أمريكي	4	2016/3/1
3	باب	$15	2	2016/3/15
4	المحرك	$100	1	2016/3/20
5	مجاميع	135.5 دولار أمريكي	7	2016/3/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,
}

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

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

لاحظ أن "الإجماليات" ، بينما لم يتم تغييره مباشرةً من خلال هذا الطلب، يتغير لأن خلاياها تحتوي على معادلات تعتمد على الخلايا التي تم تغييرها.

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

بدءًا بورقة فارغة، ما يلي spreadsheets.values.batchUpdate عينة التعليمات البرمجية كيفية كتابة القيم إلى النطاقات Sheet1!A1:A4 الورقة1!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	ب	C	D
1	المنتج/الخدمة	التكلفة	مخزن	تاريخ الشحن
2	العجلة	20.50 دولار أمريكي	4	2016/3/1
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	ب	C	D	E
1	البيانات	123.45	صواب	=MAX(D2:D4)	10
2

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

إلحاق القيم

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	مخزن	تاريخ الشحن
2	العجلة	20.50 دولار أمريكي	4	2016/3/1
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	ب	C	D
1	المنتج/الخدمة	التكلفة	مخزن	تاريخ الشحن
2	العجلة	20.50 دولار أمريكي	4	2016/3/1
3	باب	$15	2	2016/3/15
4	المحرك	$100	1	2016/3/20
5