Дополнения Google Classroom теперь общедоступны для разработчиков! Дополнительную информацию см. в документации по дополнениям .

Эта страница переведена с помощью Cloud Translation API.

Доступ к API предварительного просмотра

На этой странице описывается, как получить доступ к функциям предварительной версии Classroom API и указать предварительные версии.

При использовании функций предварительной версии по сравнению со стабильной версией API v1 необходимо учитывать три момента:

Вызывающий проект Google Cloud должен быть зарегистрирован в программе Google Workspace Developer Preview и одобрен Google.
Функции API в программах раннего доступа или предварительного просмотра не представлены в стандартных клиентских библиотеках и могут быть недоступны по умолчанию через HTTP.
В любой момент времени в режиме предварительного просмотра могут находиться несколько состояний или версий API.

Включить функции предварительного просмотра в клиентских библиотеках

Распространенный вариант использования Classroom API — клиентская библиотека. Существует три типа клиентских библиотек:

Динамически генерируемые клиентские библиотеки
Статические клиентские библиотеки, предоставленные Google
Ваша собственная клиентская библиотека

Рекомендуется использовать динамически сгенерированные или предоставленные Google статические библиотеки для работы с API. Если вам нужно собрать собственную библиотеку, см. раздел «Сборка клиентских библиотек» . Создание собственной библиотеки выходит за рамки данного руководства, но вам следует ознакомиться с разделом «Динамические библиотеки», чтобы узнать о метках предварительного просмотра и их роли в Discovery.

Динамические библиотеки

Библиотеки на таких языках, как Python, генерируют клиентскую библиотеку во время выполнения, используя Discovery Document из службы Discovery .

Документ обнаружения (Discovery Document) — это машиночитаемая спецификация для описания и использования REST API. Он используется для создания клиентских библиотек , плагинов IDE и других инструментов, взаимодействующих с API Google. Один сервис может предоставлять несколько документов обнаружения.

Документы Discovery для службы Classroom API ( classroom.googleapis.com ) можно найти в следующей конечной точке:

https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY

Важным отличием при работе с API предварительного просмотра является указание соответствующей label . Для общедоступных предварительных просмотров Classroom такой меткой является DEVELOPER_PREVIEW .

Чтобы сгенерировать библиотеку Python и создать экземпляр службы Classroom с методами предварительного просмотра, вы можете указать URL-адрес обнаружения с соответствующей службой, учетными данными и меткой:

classroom_service_with_preview_features = googleapiclient.discovery.build(
  serviceName='classroom',
  version='v1',
  credentials=credentials,
  static_discovery=False,
  discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY)'

Подробную информацию о каждом языке см. в документации по клиентской библиотеке API Google.

Статические библиотеки

Клиентские библиотеки на таких языках, как Java, Node.js, PHP, C# и Go, должны быть собраны из исходного кода. Эти библиотеки предоставляются вам и уже содержат функции предварительной версии.

Для общедоступных предварительных версий клиентские библиотеки Classroom можно найти среди других клиентских библиотек программы Workspace Developer Preview . Для получения приватных предварительных версий обратитесь к своему контактному лицу в Google, если вам нужны статические библиотеки.

Возможно, вам придется изменить типичную конфигурацию зависимостей, чтобы использовать эти локальные библиотеки вместо импорта стандартных клиентских библиотек, которые не имеют функций предварительного просмотра.

Например, чтобы использовать клиентскую библиотеку Go, вам необходимо использовать директиву replace в файле go.mod , чтобы потребовать модуль из локального каталога :

module example.com/app

go 1.21.1

require (
    golang.org/x/oauth2 v0.12.0
    google.golang.org/api v0.139.0 // Classroom library is in here.
)

require (
  ...
)

// Use a local copy of the Go client library.
replace google.golang.org/api v0.139.0 => ../google-api-go-client

В качестве другого примера, если вы используете Node.js и npm, добавьте загрузку клиентской библиотеки Node.js ( googleapis-classroom-1.0.4.tgz ) в качестве локальной зависимости в package.json :

{
  "name": "nodejs-classroom-example",
  "version": "1.0.0",
  ...
  "dependencies": {
    "@google-cloud/local-auth": "^2.1.0",
    "googleapis": "^95.0.0",
    "classroom-with-preview-features": "file:./googleapis-classroom-1.0.4.tgz"
  }
}

Затем в своем приложении потребуйте модуль classroom-with-preview-features в дополнение к обычным зависимостям и создайте экземпляр службы classroom из этого модуля:

const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithPreviewFeatures = require('classroom-with-preview-features');

...

const classroom = classroomWithPreviewFeatures.classroom({
  version: 'v1',
  auth: auth,
});

...

Укажите предварительную версию API

Независимо от того, используете ли вы статическую или динамическую библиотеку, необходимо указывать предварительную версию при выполнении вызовов API к методам с возможностями предварительного просмотра.

Различные доступные версии и их функции описаны в «Дорожной карте API класса» . Справочная документация по методам и полям также описывает, в каких версиях доступен метод или поле.

Версия указывается путём установки поля PreviewVersion в запросах. Например, чтобы создать рубрику с помощью API предварительного просмотра рубрик CRUD, необходимо установить значение previewVersion равным V1_20231110_PREVIEW в запросе CREATE:

rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id,
            courseWorkId=coursework_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW",
            body=body
).execute()

Ресурсы, связанные с вызовом метода предварительного просмотра, также содержат значение previewVersion , используемое в вызове, в виде поля, доступного только для чтения, чтобы помочь вам понять, какую версию вы используете. Например, ответ предыдущего вызова CREATE содержит значение V1_20231110_PREVIEW :

print(json.dumps(rubric, indent=4))
{
  "courseId": "123",
  "courseWorkId": "456",
  "creationTime": "2023-10-23T18:18:29.932Z",
  "updateTime": "2023-10-23T18:18:29.932Z",
  "id": "789",
  "criteria": [...],
  # The preview version used in the call that returned this resource.
  "previewVersion": "V1_20231110_PREVIEW",
  ...
}

HTTP-запросы

Также возможно использовать API Classroom напрямую по протоколу HTTP.

Если вы отправляете HTTP-запросы без клиентской библиотеки, вам всё равно необходимо включить функции предварительного просмотра и указать предварительную версию. Это делается путём установки label с заголовком X-Goog-Visibilities и указанием вышеупомянутой предварительной версии либо в качестве параметра запроса, либо в поле тела POST (см. соответствующую справочную документацию по API). Для публичных предварительных версий используется метка DEVELOPER_PREVIEW .

Например, следующий запрос curl выполняет вызов LIST к службе Rubrics с соответствующей меткой видимости и версией предварительного просмотра:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_ID/rubrics?key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --compressed

Вы также можете указать предварительную версию в теле запроса, например, при выполнении POST-запроса:

curl --request PATCH \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]"}' \
  --compressed

API для каждого HTTP-запроса описан в документации REST .

Скрипт Google Apps

Вызов API предварительной версии возможен из Google Apps Script. Однако есть несколько отличий от типичного использования Apps Script.

Вам необходимо настроить свой скрипт на использование любого проекта Google Cloud, который вы зарегистрировали в программе Developer Preview .
Расширенные службы не поддерживают методы предварительного просмотра, поэтому вам придется отправлять запросы напрямую с помощью HTTP.
Необходимо предоставить метку и предварительную версию, как описано в предыдущем разделе HTTP .

Ознакомьтесь с соответствующим кратким руководством , чтобы ознакомиться с Apps Script и настроить базовый проект. Затем следуйте этим инструкциям, чтобы начать вызывать API предварительной версии:

Измените облачный проект, используемый скриптом.

В настройках проекта нажмите «Изменить проект» и введите идентификатор облачного проекта, зарегистрированного в программе Developer Preview (по умолчанию скрипты Apps Script используют общий проект). Только зарегистрированные проекты могут вызывать методы предварительной версии.

Настроить HTTP-запросы

Затем настройте HTTP-запрос того метода, который вы хотите вызвать в редакторе . Например, в кратком руководстве список курсов с помощью сервиса Classroom выглядит так:

function listCourses() {
  try {
    const response = Classroom.Courses.list();
    const courses = response.courses;
    if (!courses || courses.length === 0) {
      console.log('No courses found.');
      return;
    }
    for (const course of courses) {
      console.log('%s (%s)', course.name, course.id);
    }
  } catch (err) {
    // TODO: Developer to handle.
    console.log(err.message);
  }
}

Эквивалентная операция с использованием HTTP напрямую:

function listCourses() {
  const response = UrlFetchApp.fetch(
        'https://classroom.googleapis.com/v1/courses', {
        method: 'GET',
        headers: {'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()},
        contentType: 'application/json',
      });
  const data = JSON.parse(response.getContentText());
  if (data.error) {
    // TODO: Developer to handle.
    console.log(err.message);
    return;
  }
  if (!data.courses || !data.courses.length) {
    console.log('No courses found.');
    return;
  }
  for (const course of data.courses) {
    console.log('%s (%s)', course.name, course.id);
  }
}

При использовании расширенных служб необходимые области OAuth определяются автоматически, но для выполнения прямых HTTP-вызовов к API Google в Apps Script необходимо вручную добавить соответствующие области.

В настройках проекта включите опцию «Показывать файл манифеста "appsscript.json" в редакторе» . Вернувшись в редактор , добавьте в файл appscript.json oauthScopes для необходимых областей действия. Области действия для данного метода перечислены на странице со справочной информацией. Например, см. страницу метода списка courses.courseWork.rubrics .

Обновленный файл appscript.json может выглядеть так:

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/classroom.coursework.students",
    "https://www.googleapis.com/auth/classroom.courses",
    "https://www.googleapis.com/auth/spreadsheets.readonly",
    "https://www.googleapis.com/auth/spreadsheets"
  ]
}

Предоставьте этикетку и предварительную версию

Вернитесь в скрипт и убедитесь, что вы добавили соответствующую метку и предварительную версию, как описано в предыдущем разделе HTTP . Пример вызова LIST к службе рубрик будет выглядеть так:

function listRubrics() {
  const courseId = COURSE_ID;
  const courseWorkId = COURSE_WORK_ID;
  const response = UrlFetchApp.fetch(
         `https://classroom.googleapis.com/v1/courses/${courseId}/courseWork/${courseWorkId}/rubrics?previewVersion=V1_20231110_PREVIEW`, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer ' + ScriptApp.getOAuthToken(),
          'X-Goog-Visibilities': 'DEVELOPER_PREVIEW'
        },
        contentType: 'application/json',
        muteHttpExceptions: true
      });
  const data = JSON.parse(response.getContentText());
  console.log(data)
  if (data.error) {
    // TODO: Developer to handle.
    console.log(error.message);
    return;
  }
  if (!data.rubrics || !data.rubrics.length) {
    console.log('No rubrics for this coursework!');
    return;
  }
  console.log(data.rubrics);
}