برای اینکه به سازندگان فرم کنترل بیشتری بر روی افرادی که میتوانند پاسخ دهند، کنترلهای جزئی را برای پاسخدهندگان معرفی میکنیم. فرم هایی که پس از 31 ژانویه 2026 با API ایجاد می شوند، به طور پیش فرض دارای وضعیت منتشر نشده خواهند بود. برای کسب اطلاعات بیشتر، تغییرات API در Google Forms را ببینید.
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
برای افزودن محتوا به فرم یا بهروزرسانی تنظیمات، فراداده یا محتوا، از متد batchUpdate() استفاده کنید، که تغییرات را با هم در یک دسته گروهبندی میکند تا در صورت شکست یکی از درخواستها، هیچ یک از تغییرات دیگر (بالقوه وابسته) نوشته نشود.
متد batchUpdate() یک بدنه پاسخ را برمی گرداند که در آن برای هر درخواست یک پاسخ وجود دارد. هر پاسخ همان شاخص درخواست مربوطه را اشغال می کند. برای درخواستهایی که پاسخ مناسبی ندارند، پاسخ در آن نمایه خالی خواهد بود.
قبل از شروع
قبل از ادامه کار در این صفحه، وظایف زیر را انجام دهید:
مجوز/تأیید هویت و تنظیمات اعتبارنامه را در دستورالعمل های Early Adopter Program کامل کنید
متادیتا، تنظیمات یا موارد را بهروزرسانی کنید
مثال زیر نحوه بهروزرسانی فراداده یک فرم را نشان میدهد، اما ساختار برای محتوا و تنظیمات یکسان است—آنها از updateItem یا درخواستهای updateSettings به جای updateFormInfo استفاده میکنند. برای هر درخواست، نام فیلدی که باید تغییر کند و مقدار به روز شده را به همراه یک مقدار updateMask برای محدود کردن تغییرات در فیلدهایی که مشخص کرده اید، ارائه می دهید.
استراحت
برای به روز رسانی توضیحات فرم، متد batchUpdate() با شناسه فرم و مقدار توضیحات به روز شده فراخوانی کنید.
نمونه بدنه درخواست
"requests":[{"updateFormInfo":{"info":{"description":"Please complete this quiz based on this week's readings for class."},"updateMask":"description"}}]
fromapiclientimportdiscoveryfromhttplib2importHttpfromoauth2clientimportclient,file,toolsSCOPES="https://www.googleapis.com/auth/forms.body"DISCOVERY_DOC="https://forms.googleapis.com/$discovery/rest?version=v1"store=file.Storage("token.json")creds=Noneifnotcredsorcreds.invalid:flow=client.flow_from_clientsecrets("client_secrets.json",SCOPES)creds=tools.run_flow(flow,store)form_service=discovery.build("forms","v1",http=creds.authorize(Http()),discoveryServiceUrl=DISCOVERY_DOC,static_discovery=False,)form={"info":{"title":"Update metadata example for Forms API!",}}# Creates the initial FormcreateResult=form_service.forms().create(body=form).execute()# Request body to add description to a Formupdate={"requests":[{"updateFormInfo":{"info":{"description":("Please complete this quiz based on this week's"" readings for class.")},"updateMask":"description",}}]}# Update the form with a descriptionquestion_setting=(form_service.forms().batchUpdate(formId=createResult["formId"],body=update).execute())# Print the result to see it now has a descriptiongetresult=form_service.forms().get(formId=createResult["formId"]).execute()print(getresult)
importpathfrom'path';import{forms}from'@googleapis/forms';import{authenticate}from'@google-cloud/local-auth';asyncfunctionupdateForm(){constauthClient=awaitauthenticate({keyfilePath:path.join(__dirname,'credentials.json'),scopes:'https://www.googleapis.com/auth/drive',});constformsClient=forms({version:'v1',auth:authClient,});constnewForm={info:{title:'Creating a new form for batchUpdate in Node',},};constcreateResponse=awaitformsClient.forms.create({requestBody:newForm,});console.log('New formId was: '+createResponse.data.formId);// Request body to add description to a Formconstupdate={requests:[{updateFormInfo:{info:{description:'Please complete this quiz based on this week\'s readings for class.',},updateMask:'description',},},],};constres=awaitformsClient.forms.batchUpdate({formId:createResponse.data.formId,requestBody:update,});console.log(res.data);returnres.data;}
یک مورد اضافه کنید
مثال زیر نحوه افزودن محتوای جدید به فرم را نشان می دهد. هنگام افزودن محتوای جدید، باید مکانی را با فهرستی ارائه کنید که در آن محتوای جدید باید درج شود. به عنوان مثال، مکانی با شاخص 0 محتوا را در ابتدای فرم درج می کند.
استراحت
برای افزودن یک آیتم به فرم، متد batchUpdate() با شناسه فرم و اطلاعات مورد و مکان مورد نظر فراخوانی کنید.
نمونه بدنه درخواست
"requests":[{"createItem":{"item":{"title":"Homework video","description":"Quizzes in Google Forms","videoItem":{"video":{"youtubeUri":"https://www.youtube.com/watch?v=Lt5HqPvM-eI"}}},"location":{"index":0}}]
fromapiclientimportdiscoveryfromhttplib2importHttpfromoauth2clientimportclient,file,toolsSCOPES="https://www.googleapis.com/auth/forms.body"DISCOVERY_DOC="https://forms.googleapis.com/$discovery/rest?version=v1"store=file.Storage("token.json")creds=Noneifnotcredsorcreds.invalid:flow=client.flow_from_clientsecrets("client_secrets.json",SCOPES)creds=tools.run_flow(flow,store)form_service=discovery.build("forms","v1",http=creds.authorize(Http()),discoveryServiceUrl=DISCOVERY_DOC,static_discovery=False,)form={"info":{"title":"Update item example for Forms API",}}# Creates the initial FormcreateResult=form_service.forms().create(body=form).execute()# Request body to add a video item to a Formupdate={"requests":[{"createItem":{"item":{"title":"Homework video","description":"Quizzes in Google Forms","videoItem":{"video":{"youtubeUri":("https://www.youtube.com/watch?v=Lt5HqPvM-eI")}},},"location":{"index":0},}}]}# Add the video to the formquestion_setting=(form_service.forms().batchUpdate(formId=createResult["formId"],body=update).execute())# Print the result to see it now has a videoresult=form_service.forms().get(formId=createResult["formId"]).execute()print(result)
importpathfrom'path';import{forms}from'@googleapis/forms';import{authenticate}from'@google-cloud/local-auth';asyncfunctionaddItem(){constauthClient=awaitauthenticate({keyfilePath:path.join(__dirname,'credentials.json'),scopes:'https://www.googleapis.com/auth/drive',});constformsClient=forms({version:'v1',auth:authClient,});constnewForm={info:{title:'Creating a new form for batchUpdate in Node',},};constcreateResponse=awaitformsClient.forms.create({requestBody:newForm,});console.log('New formId was: '+createResponse.data.formId);// Request body to add video item to a Formconstupdate={requests:[{createItem:{item:{title:'Homework video',description:'Quizzes in Google Forms',videoItem:{video:{youtubeUri:'https://www.youtube.com/watch?v=Lt5HqPvM-eI',},},},location:{index:0,},},},],};constupdateResponse=awaitformsClient.forms.batchUpdate({formId:createResponse.data.formId,requestBody:update,});console.log(updateResponse.data);returnupdateResponse.data;}
درخواست سفارش
متد batchUpdate() آرایه ای از درخواست های فرعی مانند createItem و updateItem را می پذیرد. درخواستهای فرعی به ترتیبی که ارائه میشوند، یکی یکی تأیید میشوند.
مثال: یک درخواست batchUpdate دارای یک آرایه requests با دو درخواست فرعی createItem است. درخواست فرعی A دارای location.index 0 و درخواست فرعی B دارای location.index 1 است. اگر آرایه requests [A, B] باشد، batchUpdate موفق خواهد شد. اگر آرایه [B، A] باشد، batchUpdate با شکست مواجه میشود، زیرا location.index 1 معتبر نیست، مگر اینکه فرم از قبل حاوی یک مورد در شاخص 0 باشد.
تاریخ آخرین بهروزرسانی 2025-09-10 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-09-10 بهوقت ساعت هماهنگ جهانی."],[],["The `batchUpdate()` method is used to modify forms, allowing for updates to metadata, settings, or content and the addition of new items. It groups changes, ensuring that if one fails, none are applied. When updating, the method requires the field name, updated value, and `updateMask`. Adding content requires specifying the item details and insertion `location` by index. The method executes sub-requests sequentially, validating each in order. The order in which you place requests in an array matters when creating items.\n"],null,["# Update a form or quiz\n\nTo add content to a form or update the settings, metadata, or content, use the\n`batchUpdate()` method, which groups changes together in a batch so that if one\nrequest fails, none of the other (potentially dependent) changes are written.\n\nThe `batchUpdate()` method returns a response body, within which is a response\nfor each request. Each response occupies the same index as the corresponding\nrequest; for requests with no applicable response, the response at that index\nwill be empty.\n\nBefore you begin\n----------------\n\nPerform the following tasks before proceeding with the tasks on this page:\n\n- Complete authorization/authentication and credentials setup in the Early Adopter Program instructions\n\nUpdate metadata, settings, or items\n-----------------------------------\n\nThe following example shows how to update a form's metadata, but the structure\nis the same for content and settings---they use the `updateItem` or\n`updateSettings` requests instead of `updateFormInfo`. For each request, you\nsupply the name of the field to be changed and the updated value, along with\nan `updateMask` value to limit changes to the fields you've specified. \n\n### REST\n\nTo update the form's description, call the\n[`batchUpdate()`](/workspace/forms/api/reference/rest/v1/forms/batchUpdate)\nmethod with the form ID and the updated description value.\n\n**Sample request body** \n\n \"requests\": [{\n \"updateFormInfo\": {\n \"info\": {\n \"description\": \"Please complete this quiz based on this week's readings for class.\"\n },\n \"updateMask\": \"description\"\n }\n }]\n\n### Python\n\nforms/snippets/update_form.py \n[View on GitHub](https://github.com/googleworkspace/python-samples/blob/main/forms/snippets/update_form.py) \n\n```python\nfrom apiclient import discovery\nfrom httplib2 import Http\nfrom oauth2client import client, file, tools\n\nSCOPES = \"https://www.googleapis.com/auth/forms.body\"\nDISCOVERY_DOC = \"https://forms.googleapis.com/$discovery/rest?version=v1\"\n\nstore = file.Storage(\"token.json\")\ncreds = None\nif not creds or creds.invalid:\n flow = client.flow_from_clientsecrets(\"client_secrets.json\", SCOPES)\n creds = tools.run_flow(flow, store)\n\nform_service = discovery.build(\n \"forms\",\n \"v1\",\n http=creds.authorize(Http()),\n discoveryServiceUrl=DISCOVERY_DOC,\n static_discovery=False,\n)\n\nform = {\n \"info\": {\n \"title\": \"Update metadata example for Forms API!\",\n }\n}\n\n# Creates the initial Form\ncreateResult = form_service.forms().create(body=form).execute()\n\n# Request body to add description to a Form\nupdate = {\n \"requests\": [\n {\n \"updateFormInfo\": {\n \"info\": {\n \"description\": (\n \"Please complete this quiz based on this week's\"\n \" readings for class.\"\n )\n },\n \"updateMask\": \"description\",\n }\n }\n ]\n}\n\n# Update the form with a description\nquestion_setting = (\n form_service.forms()\n .batchUpdate(formId=createResult[\"formId\"], body=update)\n .execute()\n)\n\n# Print the result to see it now has a description\ngetresult = form_service.forms().get(formId=createResult[\"formId\"]).execute()\nprint(getresult)\n```\n\n### Node.js\n\nforms/snippets/update_form.js \n[View on GitHub](https://github.com/googleworkspace/node-samples/blob/main/forms/snippets/update_form.js) \n\n```javascript\n'use strict';\n\nconst path = require('path');\nconst google = require('@googleapis/forms');\nconst {authenticate} = require('@google-cloud/local-auth');\n\nasync function runSample(query) {\n const authClient = await authenticate({\n keyfilePath: path.join(__dirname, 'credentials.json'),\n scopes: 'https://www.googleapis.com/auth/drive',\n });\n const forms = google.forms({\n version: 'v1',\n auth: authClient,\n });\n const newForm = {\n info: {\n title: 'Creating a new form for batchUpdate in Node',\n },\n };\n const createResponse = await forms.forms.create({\n requestBody: newForm,\n });\n console.log('New formId was: ' + createResponse.data.formId);\n\n // Request body to add description to a Form\n const update = {\n requests: [\n {\n updateFormInfo: {\n info: {\n description:\n 'Please complete this quiz based on this week\\'s readings for class.',\n },\n updateMask: 'description',\n },\n },\n ],\n };\n const res = await forms.forms.batchUpdate({\n formId: createResponse.data.formId,\n requestBody: update,\n });\n console.log(res.data);\n return res.data;\n}\n\nif (module === require.main) {\n runSample().catch(console.error);\n}\nmodule.exports = runSample;\n```\n\nAdd an item\n-----------\n\nThe following example shows how to add new content to a form. When adding new\ncontent, you must provide a location with an index where new content should be\ninserted. For instance, a location with index `0` will insert the content at\nthe beginning of the form. \n\n### REST\n\nTo add an item to the form, call the\n[`batchUpdate()`](/workspace/forms/api/reference/rest/v1/forms/batchUpdate)\nmethod with the form ID and the item's information and desired location.\n\n**Sample request body** \n\n \"requests\": [{\n \"createItem\": {\n \"item\": {\n \"title\": \"Homework video\",\n \"description\": \"Quizzes in Google Forms\",\n \"videoItem\": {\n \"video\": {\n \"youtubeUri\": \"https://www.youtube.com/watch?v=Lt5HqPvM-eI\"\n }\n }},\n \"location\": {\n \"index\": 0\n }\n }]\n\n### Python\n\nforms/snippets/add_item.py \n[View on GitHub](https://github.com/googleworkspace/python-samples/blob/main/forms/snippets/add_item.py) \n\n```python\nfrom apiclient import discovery\nfrom httplib2 import Http\nfrom oauth2client import client, file, tools\n\nSCOPES = \"https://www.googleapis.com/auth/forms.body\"\nDISCOVERY_DOC = \"https://forms.googleapis.com/$discovery/rest?version=v1\"\n\nstore = file.Storage(\"token.json\")\ncreds = None\nif not creds or creds.invalid:\n flow = client.flow_from_clientsecrets(\"client_secrets.json\", SCOPES)\n creds = tools.run_flow(flow, store)\n\nform_service = discovery.build(\n \"forms\",\n \"v1\",\n http=creds.authorize(Http()),\n discoveryServiceUrl=DISCOVERY_DOC,\n static_discovery=False,\n)\n\nform = {\n \"info\": {\n \"title\": \"Update item example for Forms API\",\n }\n}\n\n# Creates the initial Form\ncreateResult = form_service.forms().create(body=form).execute()\n\n# Request body to add a video item to a Form\nupdate = {\n \"requests\": [\n {\n \"createItem\": {\n \"item\": {\n \"title\": \"Homework video\",\n \"description\": \"Quizzes in Google Forms\",\n \"videoItem\": {\n \"video\": {\n \"youtubeUri\": (\n \"https://www.youtube.com/watch?v=Lt5HqPvM-eI\"\n )\n }\n },\n },\n \"location\": {\"index\": 0},\n }\n }\n ]\n}\n\n# Add the video to the form\nquestion_setting = (\n form_service.forms()\n .batchUpdate(formId=createResult[\"formId\"], body=update)\n .execute()\n)\n\n# Print the result to see it now has a video\nresult = form_service.forms().get(formId=createResult[\"formId\"]).execute()\nprint(result)\n```\n\n### Node.js\n\nforms/snippets/add_item.js \n[View on GitHub](https://github.com/googleworkspace/node-samples/blob/main/forms/snippets/add_item.js) \n\n```javascript\n'use strict';\n\nconst path = require('path');\nconst google = require('@googleapis/forms');\nconst {authenticate} = require('@google-cloud/local-auth');\n\nasync function runSample(query) {\n const authClient = await authenticate({\n keyfilePath: path.join(__dirname, 'credentials.json'),\n scopes: 'https://www.googleapis.com/auth/drive',\n });\n const forms = google.forms({\n version: 'v1',\n auth: authClient,\n });\n const newForm = {\n info: {\n title: 'Creating a new form for batchUpdate in Node',\n },\n };\n const createResponse = await forms.forms.create({\n requestBody: newForm,\n });\n console.log('New formId was: ' + createResponse.data.formId);\n\n // Request body to add video item to a Form\n const update = {\n requests: [\n {\n createItem: {\n item: {\n title: 'Homework video',\n description: 'Quizzes in Google Forms',\n videoItem: {\n video: {\n youtubeUri: 'https://www.youtube.com/watch?v=Lt5HqPvM-eI',\n },\n },\n },\n location: {\n index: 0,\n },\n },\n },\n ],\n };\n const updateResponse = await forms.forms.batchUpdate({\n formId: createResponse.data.formId,\n requestBody: update,\n });\n console.log(updateResponse.data);\n return updateResponse.data;\n}\n\nif (module === require.main) {\n runSample().catch(console.error);\n}\nmodule.exports = runSample;\n```\n\nRequest order\n-------------\n\nThe [`batchUpdate()`](/workspace/forms/api/reference/rest/v1/forms/batchUpdate)\nmethod accepts an array of sub-requests such as `createItem` and `updateItem`.\nSub-requests are validated one at a time in the order they are provided.\n\nExample: A `batchUpdate` request has a `requests` array with two `createItem`\nsub-requests. Sub-request A has `location.index` 0 and sub-request B has\n`location.index` 1. If the `requests` array is \\[A, B\\], `batchUpdate` will\nsucceed. If the array is \\[B, A\\], `batchUpdate` will fail, since `location.index`\n1 is not valid unless the form already contains an item at index 0."]]