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

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

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

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

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

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

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

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

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

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

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

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

Документ Discovery — это машиночитаемая спецификация для описания и использования 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-адрес Discovery с соответствующим сервисом, учетными данными и меткой:

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

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

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

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

Для публичного предварительного просмотра клиентские библиотеки Classroom можно найти среди других клиентских библиотек программы Workspace Developer Preview Program . Для закрытого предварительного просмотра обратитесь к своему контактному лицу в 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 к методам с поддержкой предварительного просмотра необходимо указывать версию для предварительной версии.

Различные доступные версии и включенные в них функции описаны в дорожной карте Classroom 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 Script

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

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

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

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

В настройках проекта нажмите «Изменить проект» и введите идентификатор облачного проекта, который вы зарегистрировали в программе предварительного просмотра для разработчиков (по умолчанию скрипты 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" в редакторе ». Вернувшись в редактор , добавьте oauthScopes в файл appscript.json для необходимых вам областей действия. Области действия для конкретного метода перечислены на странице справочника. Например, см. страницу списка методов 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 к сервису Rubrics будет выглядеть следующим образом:

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);
}

Доступ к API предварительного просмотра Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.