Batchanfragen

In diesem Dokument erfahren Sie, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl von HTTP-Verbindungen für den Client zu reduzieren.

In diesem Dokument geht es speziell um das Erstellen einer Batchanfrage durch Senden einer HTTP-Anfrage. Wenn Sie stattdessen eine Google-Clientbibliothek für die Batchanfrage verwenden, finden Sie entsprechende Informationen in der Dokumentation der Clientbibliothek.

Übersicht

Jede HTTP-Verbindung, die der Client erstellt, führt zu einem bestimmten Overhead. Die Google Classroom API unterstützt Stapelanfragen, damit Ihr Kunde mehrere API-Aufrufe in einer einzigen HTTP-Anfrage zusammenfassen kann.

Fallbeispiele für den Einsatz von Batchanfragen:

Teilnehmerlisten für eine große Anzahl von Kursen abrufen
Mehrere Kurse gleichzeitig erstellen oder aktualisieren
Eine große Anzahl von Teilnehmerlisten hinzufügen
Kurslisten für eine große Anzahl von Nutzern abrufen

In jedem Fall können Sie die Aufrufe in einer einzigen HTTP-Anfrage gruppieren, anstatt jeden Aufruf einzeln zu senden. Alle internen Anfragen müssen an dieselbe Google API gesendet werden.

Pro Batchanfrage sind maximal 50 Aufrufe möglich. Wenn Sie mehr Aufrufe ausführen müssen, verwenden Sie mehrere Batchanfragen.

Hinweis: Die Batchverarbeitung der Google Classroom API verwendet dieselbe Syntax wie die Batchverarbeitung von OData, jedoch mit einer anderen Semantik.

Batchdetails

Eine Batchanfrage besteht aus mehreren, in einer HTTP-Anfrage zusammengefassten API-Aufrufen. Sie kann an den im Discovery-Dokument der API angegebenen batchPath gesendet werden. Der Standardpfad ist /batch/api_name/api_version. In diesem Abschnitt wird die Batchsyntax im Detail beschrieben. Anschließend finden Sie ein Beispiel.

Hinweis: Eine Reihe von n-Anfragen in einem Stapel wird auf Ihr Nutzungslimit als n-Anfragen angerechnet, nicht als eine Anfrage. Die Batchanfrage wird vor der Verarbeitung in eine Reihe von Anfragen aufgeteilt.

Format einer Batchanfrage

Eine Batchanfrage ist eine einzelne Standard-HTTP-Anfrage, die mehrere Google Classroom API-Aufrufe enthält. Dabei wird der Inhaltstyp multipart/mixed verwendet. Jeder Teil der HTTP-Hauptanfrage enthält eine verschachtelte HTTP-Anfrage.

Jeder Teil beginnt mit seinem eigenen HTTP-Header Content-Type: application/http. Er kann auch einen optionalen Content-ID-Header haben. Die Header der einzelnen Teile sollen jedoch nur den Anfang des Teils markieren. Sie sind von der verschachtelten Anfrage getrennt. Nachdem der Server die Batchanfrage in separate Anfragen aufgeteilt hat, werden die Header der einzelnen Teile ignoriert.

Der Text jedes Teils ist an sich eine vollständige HTTP-Anfrage mit eigenem Verb, eigener URL, eigenen Headern und eigenem Text. Die HTTP-Anfrage darf nur den Pfadteil der URL enthalten; vollständige URLs sind in Batchanfragen nicht zulässig.

Die HTTP-Header für die äußere Batchanfrage gelten für jede Anfrage in dem Batch, ausgenommen Content--Header wie Content-Type. Wenn Sie einen bestimmten HTTP-Header sowohl in der äußeren Anfrage als auch in einem individuellen Aufruf verwenden, überschreibt der Wert des individuellen Aufrufheaders den Wert des Headers der äußeren Stapelanfrage. Die Header für einen individuellen Aufruf gelten nur für diesen Aufruf.

Beispiel: Wenn Sie einen Autorisierungsheader für einen bestimmten Aufruf angeben, gilt dieser Header nur für diesen Aufruf. Wenn Sie einen Autorisierungsheader für die äußere Anfrage angeben, gilt dieser Header für alle einzelnen Aufrufe, es sei denn, diese überschreiben ihn mit eigenen Autorisierungsheadern.

Wenn der Server die Stapelanfrage empfängt, wendet er (nach Bedarf) die Abfrageparameter und Header der äußeren Anfrage für jeden Teil an, und behandelt jeden Teil dann so, als wäre er eine separate HTTP-Anfrage.

Antwort auf eine Batchanfrage

Die Antwort des Servers ist eine einzelne Standard-HTTP-Antwort mit einem Inhaltstyp multipart/mixed. Jeder Teil ist die Antwort auf eine der Anfragen in der Batchanfrage in derselben Reihenfolge wie die einzelnen Anfragen.

Wie die Teile in der Anfrage enthält jeder Antwortteil eine vollständige HTTP-Antwort, einschließlich Statuscode, Headern und Text. Wie auch bei den Teilen in der Anfrage ist jedem Antwortteil ein Content-Type-Header vorangestellt, der den Beginn des Teils markiert.

Wenn ein bestimmter Teil einer Anfrage einen Content-ID-Header enthielt, enthält der entsprechende Teil der Antwort einen übereinstimmenden Content-ID-Header, wobei dem ursprünglichen Wert der String response- vorangestellt ist, wie im folgenden Beispiel dargestellt.

Hinweis: Der Server kann die Aufrufe in beliebiger Reihenfolge ausführen. Die Aufrufe werden nicht unbedingt in der Reihenfolge ausgeführt, in der Sie sie angegeben haben. Wenn Sie sicherstellen möchten, dass zwei Aufrufe in einer bestimmten Reihenfolge ausgeführt werden, können Sie sie nicht in einer einzelnen Anfrage senden. Senden Sie stattdessen den ersten Aufruf für sich alleine und warten Sie auf die Antwort auf den ersten Aufruf, bevor Sie den zweiten Aufruf senden.

Beispiel

Das folgende Beispiel zeigt die Verwendung der Batchverarbeitung mit der Google Classroom API.

Beispiel-Batchanfrage

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--

Beispiel für eine Stapelantwort

Dies ist die Antwort auf die Beispielanfrage im vorherigen Abschnitt.

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--

Clientbibliotheken verwenden

Die folgenden Codebeispiele zeigen, wie Batchanfragen mit den Google APIs-Clientbibliotheken gestellt werden. Weitere Informationen zum Installieren und Einrichten der Bibliotheken finden Sie in den entsprechenden Kurzanleitungen.

.NET

Classroom/snippets/ClassroomSnippets/BatchAddStudents.cs

Auf GitHub ansehen

using Google;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Classroom.v1;
using Google.Apis.Classroom.v1.Data;
using Google.Apis.Requests;
using Google.Apis.Services;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace ClassroomSnippets
{
    // Class to demonstrate the use of Classroom Batch Add Students API
    public class BatchAddStudents
    {
        /// <summary>
        /// Add multiple students in a specified course.
        /// </summary>
        /// <param name="courseId">Id of the course to add students.</param>
        /// <param name="studentEmails">Email address of the students.</param>
        public static void ClassroomBatchAddStudents(string courseId,
            List<string> studentEmails)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for 
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(ClassroomService.Scope.ClassroomRosters);

                // Create Classroom API service.
                var service = new ClassroomService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Classroom Snippets"
                });

                var batch = new BatchRequest(service, "https://classroom.googleapis.com/batch");
                BatchRequest.OnResponse<Student> callback = (student, error, i, message) =>
                {
                    if (error != null)
                    {
                        Console.WriteLine("Error adding student to the course: {0}", error.Message);
                    }
                    else
                    {
                        Console.WriteLine("User '{0}' was added as a student to the course.",
                            student.Profile.Name.FullName);
                    }
                };
                foreach (var studentEmail in studentEmails)
                {
                    var student = new Student() {UserId = studentEmail};
                    var request = service.Courses.Students.Create(student, courseId);
                    batch.Queue<Student>(request, callback);
                }

                Task.WaitAll(batch.ExecuteAsync());
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else if (e is GoogleApiException)
                {
                    Console.WriteLine("Course does not exist.");
                }
                else
                {
                    throw;
                }
            }
        }
    }
}

Java

Classroom/snippets/src/main/java/BatchAddStudents.java

Auf GitHub ansehen

import com.google.api.client.googleapis.batch.BatchRequest;
import com.google.api.client.googleapis.batch.json.JsonBatchCallback;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.http.HttpHeaders;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.classroom.Classroom;
import com.google.api.services.classroom.ClassroomScopes;
import com.google.api.services.classroom.model.Student;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/* Class to demonstrate the use of Classroom Batch Add Students API */
public class BatchAddStudents {

  /* Scopes required by this API call. If modifying these scopes, delete your previously saved
  tokens/ folder. */
  static ArrayList<String> SCOPES =
      new ArrayList<>(Arrays.asList(ClassroomScopes.CLASSROOM_ROSTERS));

  /**
   * Add multiple students in a specified course.
   *
   * @param courseId - Id of the course to add students.
   * @param studentEmails - Email address of the students.
   * @throws IOException - if credentials file not found.
   * @throws GeneralSecurityException - if a new instance of NetHttpTransport was not created.
   */
  public static void batchAddStudents(String courseId, List<String> studentEmails)
      throws GeneralSecurityException, IOException {

    // Create the classroom API client.
    final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
    Classroom service =
        new Classroom.Builder(
                HTTP_TRANSPORT,
                GsonFactory.getDefaultInstance(),
                ClassroomCredentials.getCredentials(HTTP_TRANSPORT, SCOPES))
            .setApplicationName("Classroom samples")
            .build();

    BatchRequest batch = service.batch();
    JsonBatchCallback<Student> callback =
        new JsonBatchCallback<>() {
          public void onSuccess(Student student, HttpHeaders responseHeaders) {
            System.out.printf(
                "User '%s' was added as a student to the course.\n",
                student.getProfile().getName().getFullName());
          }

          public void onFailure(GoogleJsonError error, HttpHeaders responseHeaders) {
            System.out.printf("Error adding student to the course: %s\n", error.getMessage());
          }
        };
    for (String studentEmail : studentEmails) {
      Student student = new Student().setUserId(studentEmail);
      service.courses().students().create(courseId, student).queue(batch, callback);
    }
    batch.execute();
  }
}

PHP

Classroom/snippets/src/ClassroomBatchAddStudents.php

Auf GitHub ansehen

use Google\Client;
use Google\Service\Classroom;
use Google\Service\Classroom\Student;
use Google\Service\Exception;

function batchAddStudents($courseId, $studentEmails)
{
    /* Load pre-authorized user credentials from the environment.
    TODO(developer) - See https://developers.google.com/identity for
     guides on implementing OAuth2 for your application. */
    $client = new Client();
    $client->useApplicationDefaultCredentials();
    $client->addScope("https://www.googleapis.com/auth/classroom.profile.emails");
    $service = new Classroom($client);
    $service->getClient()->setUseBatch(true);
    //create batch
    $batch = $service->createBatch();
    foreach ($studentEmails as $studentEmail) {
        $student = new Student([
            'userId' => $studentEmail
        ]);
        $request = $service->courses_students->create($courseId, $student);
        $requestId = $studentEmail;
        $batch->add($request, $requestId);
    }
    //executing request
    $results = $batch->execute();
    foreach ($results as $responseId => $student) {
        $studentEmail = substr($responseId, strlen('response-') + 1);
        if ($student instanceof Exception) {
            $e = $student;
            printf("Error adding user '%s' to the course: %s\n", $studentEmail,
                $e->getMessage());
        } else {
            printf("User '%s' was added as a student to the course.\n",
                $student->profile->name->fullName, $courseId);
        }
    }
    $service->getClient()->setUseBatch(false);
    return $results;
}

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)