Les modules complémentaires Google Classroom sont désormais disponibles pour tous les développeurs. Pour en savoir plus, consultez la documentation sur les modules complémentaires.

Cette page a été traduite par l'API Cloud Translation.

Effectuer des requêtes par lot

Ce document explique comment autoriser les appels d'API par lot pour réduire le nombre de connexions HTTP que votre client doit effectuer.

Vous allez plus spécifiquement apprendre à exécuter une requête par lot en envoyant une requête HTTP. Si vous souhaitez plutôt exécuter ce type de requête à l'aide d'une bibliothèque cliente Google, consultez la documentation associée à la bibliothèque en question.

Présentation

Chaque connexion HTTP effectuée par votre client entraîne certains coûts. L'API Google Classroom accepte les requêtes par lot, ce qui permet à votre client d'intégrer plusieurs appels d'API dans une seule requête HTTP.

Voici quelques exemples de situations dans lesquelles l'utilisation de requêtes par lot peut s'avérer utile :

Récupération des listes de cours pour un grand nombre de cours.
Créer ou mettre à jour des cours de manière groupée
Ajouter un grand nombre de listes de cours
Récupérer des listes de cours pour un grand nombre d'utilisateurs

Dans chacun de ces cas, vous pouvez regrouper plusieurs appels en une seule requête HTTP plutôt que de les envoyer séparément. Toutes les requêtes internes doivent être transmises à la même API Google.

Une même requête par lot peut contenir jusqu'à 50 appels. Si vous devez effectuer plus d'appels, utilisez plusieurs requêtes par lot.

Remarque: Le système de requêtes par lot de l'API Google Classroom utilise la même syntaxe que le système de traitement par lot OData, mais la sémantique diffère.

Informations sur les lots

Une requête par lot est constituée de plusieurs appels d'API combinés en une seule requête HTTP, qui peut être envoyée au chemin batchPath spécifié dans le document de découverte des API. Le chemin par défaut est /batch/api_name/api_version. Cette section décrit la syntaxe des requêtes par lot plus en détail. Vous en trouverez un exemple plus bas.

Remarque : Un ensemble de n requêtes regroupées est comptabilisé comme n requêtes dans votre limite d'utilisation, et non comme une seule. Avant d'être traitée, la requête par lot est décomposée en un ensemble de requêtes.

Format d'une requête par lot

Une requête par lot est une requête HTTP standard unique qui comprend plusieurs appels d'API Google Classroom et utilise le type de contenu multipart/mixed. Chacune des parties de cette requête HTTP principale contient une requête HTTP imbriquée.

Chaque partie commence par son en-tête HTTP Content-Type: application/http, mais peut également comporter un en-tête Content-ID facultatif. Les en-têtes des différentes parties ne servent toutefois qu'à signaler le début des parties et sont séparés de la requête imbriquée. Une fois que le serveur a décomposé la requête par lot en requêtes distinctes, les en-têtes de parties sont ignorés.

Le corps de chaque partie est lui-même composé d'une requête HTTP complète dotée de son propre verbe, de son URL, de ses en-têtes et de son corps. Comme les requêtes par lot n'acceptent pas les URL complètes, la requête HTTP ne doit contenir que le chemin de l'URL.

Les en-têtes HTTP des requêtes par lot externes s'appliquent à toutes les requêtes au sein du lot, à l'exception des en-têtes Content- tels que Content-Type. Si vous spécifiez un en-tête HTTP spécifique à la fois dans la requête externe et dans un appel individuel, la valeur de l'en-tête de l'appel individuel remplace alors celle de la requête par lot externe. Les en-têtes d'un appel individuel ne s'appliquent qu'à cet appel.

Par exemple, si vous fournissez un en-tête "Authorization" à un appel spécifique, l'en-tête ne s'applique qu'à cet appel. Mais si vous fournissez un en-tête "Authorization" à la requête externe, il s'applique à tous les appels individuels, sauf s'ils le remplacent par leurs propres en-têtes "Authorization".

Lorsque le serveur reçoit la requête par lot, il applique les paramètres de requête et les en-têtes (selon le cas) de la requête externe à chaque partie, puis traite ces parties comme s'il s'agissait de requêtes HTTP distinctes.

Réponse à une requête par lot

La réponse du serveur est une réponse HTTP standard unique avec un type de contenu multipart/mixed. Chaque partie constitue la réponse à l'une des requêtes de la requête par lot et apparaît dans le même ordre que celles-ci.

À l'instar des parties de la requête, les parties de la réponse contiennent chacune une réponse HTTP complète, qui comprend un code d'état, des en-têtes et un corps. Elles sont aussi précédées d'un en-tête Content-Type signalant le début de la partie.

Si une partie donnée de la requête possède un en-tête Content-ID, la partie correspondante de la réponse dispose alors du même en-tête Content-ID, avec une valeur initiale précédée de la chaîne response-, comme le montre l'exemple suivant.

Remarque : Le serveur peut effectuer vos appels dans n'importe quel ordre. Ne vous attendez pas à ce qu'ils soient exécutés selon l'ordre dans lequel vous les avez spécifiés. Si vous souhaitez que deux appels se produisent dans un ordre donné, évitez de les envoyer dans la même requête. Vous devez plutôt envoyer le premier appel seul, attendre la réponse, puis envoyer le second.

Exemple

L'exemple suivant montre comment utiliser les requêtes par lot avec l'API Google Classroom.

Exemple de requête par lot

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

Exemple de réponse par lot

Il s'agit de la réponse à l'exemple de requête abordé dans la section précédente.

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

Bibliothèques clientes

Les exemples de code suivants montrent comment effectuer des requêtes par lot à l'aide des bibliothèques clientes d'API Google. Pour en savoir plus sur l'installation et la configuration des bibliothèques, consultez les guides de démarrage rapide respectifs.

.NET

classroom/snippets/ClassroomSnippets/BatchAddStudents.cs

Afficher sur GitHub

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

Afficher sur GitHub

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

Afficher sur GitHub

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)

Améliorer les performances