[null,null,["最后更新时间 (UTC)：2025-07-31。"],[],[],null,["# How requests work\n\nThis page describes a high-level overview of how requests work in the\nGoogle Classroom API. The goal is to aid readers who aren't already familiar with\nresource-oriented design or Google Workspace APIs.\n\nFor specific code samples, see the corresponding API guides, for example [Create\n\\& manage courses](/workspace/classroom/guides/manage-courses) or [Create \\& manage coursework](/workspace/classroom/guides/manage-coursework).\n\nResource-oriented design\n------------------------\n\nAs mentioned in [API resources](/workspace/classroom/guides/key-concepts/api-structure), the Classroom API follows\n[resource-oriented design](https://google.aip.dev/121) patterns. Most resources have methods for standard\noperations like creating, reading, updating, and deleting instances of the\nresource.\n\nFor example, it's possible to [`create()`](/workspace/classroom/reference/rest/v1/courses/create), [`patch()`](/workspace/classroom/reference/rest/v1/courses/patch), [`get()`](/workspace/classroom/reference/rest/v1/courses/get), [`list()`](/workspace/classroom/reference/rest/v1/courses/list),\nand [`delete()`](/workspace/classroom/reference/rest/v1/courses/delete) a Classroom [`Course`](/workspace/classroom/reference/rest/v1/courses) using the API.\n\nCreate\n------\n\nTo create a new resource, like a `Course`, call the `create()` method for the\ncorresponding resource.\n\n`Create()` calls always require the initial, critical details of the\ncorresponding resource as input. For example, to create a `Course`, call the\n`create()` method on the `Course` resource and specify the `name` and\n`description` in the request, along with optional information like the `room`.\n\nFor subresources (sometimes called child resources), identifiers for the parent\nresource are also required. For example, when creating a [`CourseWork`](/workspace/classroom/reference/rest/v1/courses.courseWork) within a\n`Course`, the `Course` `id` is needed to establish in which `Course` the\n`CourseWork` belongs.\n\n`Create()` methods return an instance of the newly created resource in the API\ncall response. The returned resource typically has any additional,\nserver-generated fields, such as the resource `id` or `creationTime`.\n\nPatch\n-----\n\nTo modify existing resources, call the `patch()` method (which is sometimes\ncalled `update()`) on the corresponding resource. The `patch()` method is almost\nidentical to `create()`, with two key differences; when calling the `patch()`\nmethod you must specify:\n\n1. The `id` of the resource to modify.\n2. A list of fields, called an `updateMask`, to determine which fields on the resource to update. This is optional in cases where there is a default set of fields or the fields are inferred.\n\n| **Tip:** You might notice `update()` methods alongside `patch()` methods. While both modify a resource, they differ in behavior. `Update()` completely replaces a resource with a new one, while `patch()` only updates select fields. For example, [`courses.update()`](/workspace/classroom/reference/rest/v1/courses/update) replaces an entire existing `Course`, while [`courses.patch()`](/workspace/classroom/reference/rest/v1/courses/patch) uses the aforementioned `fieldMask` to modify only specific fields in the `Course`. For simplicity, the Google Classroom API almost exclusively uses `patch()`, and it's recommended that you use that method generally.\n\n`Patch()` methods return the full instance of the updated resource in the API\ncall response, with all changes completed.\n\nGet and list\n------------\n\nThere are two methods for retrieving resources: `get()` and `list()`.\n\nThe `get()` method retrieves a specific resource by some identifier. For\nexample, fetching a `Course` based on `id` or [`alias`](/workspace/classroom/reference/rest/v1/courses.aliases). The `get()` call\nreturns the full resource directly.\n\nThe `list()` method retrieves multiple resources of the same type in a single\nrequest, without the need for the individual resource identifiers. Often the\n`list()` operation gets all the subresources of some parent resource, for\nexample, retrieving all the `CourseWork` within a `Course`. This is useful for\nminimizing requests, compared to making multiple `get()` calls, and particularly\nvaluable when you don't know the `id` of the resources you want.\n\nGenerally, `list()` methods have some maximum amount of resources that can be\nreturned in a single call, and lower limits can be configured by including a\n`pageSize` value with the call. In cases where there are more resources than the\nlimit, the `list()` method supports *pagination* ; each \"page\" of results that is\nreturned provides a `pageToken`, which can be included in a subsequent `list()`\ncall to fetch the next batch of resources.\n\nDelete\n------\n\nThe `delete()` method accepts a resource identifier, like `id`, and deletes the\ncorresponding resource. If the `delete()` is successful, an empty response is\nreturned.\n\nOther operations\n----------------\n\nNot all operations possible with the Classroom API can be achieved\nwith the aforementioned standard operations, for example, modifying the\nassignees of a `CourseWork` resource. In these cases, custom methods are\navailable, like the [`modifyAssignees`](/workspace/classroom/reference/rest/v1/courses.courseWork/modifyAssignees) method. The behavior of these methods\nare bespoke and you should consult the documentation for them individually."]]
