本文档介绍了如何对 API 调用进行批处理以减少客户端必须建立的 HTTP 连接数量。
本文档专门介绍了如何通过发送 HTTP 请求来发出批处理请求。如果您要使用某个 Google 客户端库来发出批处理请求,请参阅该客户端库的说明文档。
概览
客户端建立的每个 HTTP 连接都会产生一定的开销。Google Classroom API 支持批处理,这样您的客户端就可以将多个 API 调用组合为一个 HTTP 请求。
在以下示例情况下,您可能需要使用批处理:
- 检索大量课程的学生名单。
- 批量创建或更新课程。
- 添加大量课程名单。
- 检索大量用户的课程列表。
在上述每种情况下,您都可以将这些调用组合成一个 HTTP 请求,而不是单独发送每个调用。请注意,所有内部请求都必须发送到同一 Google API。
单个批量请求最多可以包含 50 次调用。如果必须进行更多次调用,请使用多个批量请求。
注意:Google Classroom API 的批处理系统使用的语法与 OData 批处理系统相同,但语义有所不同。
批量详情
批量请求就是将多个 API 调用进行合并而形成的一个 HTTP 请求,您可以将此请求发送到 API 发现文档中指定的 batchPath
。默认路径为 /batch/api_name/api_version
。本部分详细介绍了批处理语法,随后还会提供一个示例。
注意:一组一起进行批处理的 n 个请求将按 n 个请求(而非一个请求)计入用量限额。在处理之前,系统会将批量请求拆分为一组请求。
批量请求的格式
批量请求是一个包含多个 Google Classroom API 调用的标准 HTTP 请求,使用 multipart/mixed
内容类型。在此主 HTTP 请求中,每个部分都包含一个内嵌的 HTTP 请求。
各个部分都以其自身的 Content-Type: application/http
标头开头。您还可以选择添加一个 Content-ID
标头。不过,每个部分的标头仅用于标记该部分的开头,而与嵌套请求无关。在服务器将批量请求拆分为多个单独请求之后,每个部分的标头就会被忽略。
各个部分的正文是一个完整的 HTTP 请求,各自有专用的动词、网址、标头和正文。此 HTTP 请求必须仅包含网址的路径部分;不允许在批量请求中使用完整的网址。
外部批量请求的 HTTP 标头应用于批次中的每个请求,但 Content-Type
之类的 Content-
标头除外。如果您在外部请求和个别调用中都指定了特定的 HTTP 标头,则个别调用标头的值将替换外部批量请求标头的值。另请注意,单个调用的标头仅应用于该调用本身。
例如,如果您为特定调用提供了 Authorization 标头,则该标头仅应用于该调用。如果您为外部请求提供了 Authorization 标头,则该标头将应用于所有的单个调用,除非单个调用将其替换为自身的 Authorization 标头。
当服务器收到批处理请求时,会将外部请求的查询参数和标头(如果适用)应用于各部分,然后将各部分视作单独的 HTTP 请求进行处理。
对批量请求的响应
服务器的响应是一个标准的 HTTP 响应,使用 multipart/mixed
内容类型;其中的每个部分分别是对批量请求中一个请求的响应,且顺序与这些请求相同。
和请求中的各部分一样,响应中的各部分都包含一个完整的 HTTP 响应,其中包括状态代码、标头和正文。此外,和请求中的各部分一样,响应中的各部分均以 Content-Type
标头为前缀,用于标记各部分的开头。
如果请求的某个特定部分具有 Content-ID
标头,则响应的对应部分也会有相同的 Content-ID
标头,其格式为在原始值前面加上 response-
字符串,如下例所示。
注意:服务器可能会以任何顺序执行您的调用,因此不要预期这些调用将会以您指定的顺序执行。如果要确保两个调用以指定顺序执行,就不能在单个请求中发送这两个调用。正确的做法是,先单独发送第一个调用,等收到其响应之后再发送第二个。
示例
以下示例展示了如何将批处理与 Google Classroom API 结合使用。
批量请求示例
POST https://classroom.googleapis.com/batch HTTP/1.1 Authorization: Bearer your_auth_token Content-Type: multipart/mixed; boundary=batch_foobarbaz Content-Length: total_content_length --batch_foobarbaz Content-Type: application/http Content-Transfer-Encoding: binary MIME-Version: 1.0 Content-ID: <item1:12930812@classroom.example.com> PATCH /v1/courses/134529639?updateMask=name HTTP/1.1 Content-Type: application/json; charset=UTF-8 Authorization: Bearer your_auth_token { "name": "Course 1" } --batch_foobarbaz Content-Type: application/http Content-Transfer-Encoding: binary MIME-Version: 1.0 Content-ID: <item2:12930812@classroom.example.com> PATCH /v1/courses/134529901?updateMask=section HTTP/1.1 Content-Type: application/json; charset=UTF-8 Authorization: Bearer your_auth_token { "section": "Section 2" } --batch_foobarbaz--
批量响应示例
此部分是对上一部分中的示例请求的响应。
HTTP/1.1 200 Content-Length: response_total_content_length Content-Type: multipart/mixed; boundary=batch_foobarbaz --batch_foobarbaz Content-Type: application/http Content-ID: <response-item1:12930812@classroom.example.com> HTTP/1.1 200 OK Content-Type application/json Content-Length: response_part_1_content_length { "id": "134529639", "name": "Course 1", "section": "Section 1", "ownerId": "116269102540619633451", "creationTime": "2015-06-25T14:23:56.535Z", "updateTime": "2015-06-25T14:33:06.583Z", "enrollmentCode": "6paeflo", "courseState": "PROVISIONED", "alternateLink": "http://classroom.google.com/c/MTM0NTI5NjM5" } --batch_foobarbaz Content-Type: application/http Content-ID: <response-item2:12930812@classroom.example.com> HTTP/1.1 200 OK Content-Type: application/json Content-Length: response_part_2_content_length { "id": "134529901", "name": "Course 1", "section": "Section 2", "ownerId": "116269102540619633451", "creationTime": "2015-06-25T14:23:08.761Z", "updateTime": "2015-06-25T14:33:06.490Z", "enrollmentCode": "so75ha5", "courseState": "PROVISIONED", "alternateLink": "http://classroom.google.com/c/MTM0NTI5OTAx" } --batch_foobarbaz--
使用客户端库
以下代码示例演示了如何使用 Google API 客户端库发出批量请求。如需详细了解如何安装和设置这些库,请参阅相应的快速入门指南。
.NET
Java
PHP
Python
course_id = '123456' student_emails = ['alice@example.edu', 'bob@example.edu'] def callback(request_id, response, exception): if exception is not None: print 'Error adding user "{0}" to the course course: {1}'.format( request_id, exception) else: print 'User "{0}" added as a student to the course.'.format( response.get('profile').get('name').get('fullName')) batch = service.new_batch_http_request(callback=callback) for student_email in student_emails: student = { 'userId': student_email } request = service.courses().students().create(courseId=course_id, body=student) batch.add(request, request_id=student_email) batch.execute(http=http)