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

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

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

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

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

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

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

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

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

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

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

Документы Discovery для службы API Classroom ( 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 Roadmap . Справочная документация по методам и полям также описывает, в какой версии(ях) доступен метод или поле.

Указание версии выполняется путем установки поля 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()

Примечание: Предварительные версии предназначены для временного использования, пока функции проверяются на общедоступность в API v1. Поведение предварительной версии может измениться после окна устаревания. См. Дорожную карту API Classroom для получения дополнительной информации.

Ресурсы, связанные с вызовом метода предварительного просмотра, также содержат 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",
  ...
}

Примечание: Предварительная версия, связанная с ресурсом, соответствует версии, используемой для извлечения ресурса, а не обязательно вызову для создания ресурса; если вы сделаете будущий вызов GET, LIST или PATCH с указанием новой версии, будет возвращена новая версия.

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.

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

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

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

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

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

Далее настройте HTTP-запрос любого метода, который вы хотите вызвать обратно в Editor . Например, в quickstart список курсов с помощью службы 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 необходимо вручную добавить соответствующие области действия.

В Project Settings включите Show "appsscript.json" manifest file in editor . Вернитесь в Editor и добавьте 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);
}