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

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

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

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

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

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

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

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

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

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

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

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

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

Важным отличием работы с API предварительного просмотра является указание соответствующей label . Для общедоступных предварительных версий Класса этот ярлык — 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)'

Подробную информацию о каждом языке см. в документации по отдельной клиентской библиотеке 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 предварительного просмотра Rubrics 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. Однако есть несколько отличий от обычного использования Apps Script.

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

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

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

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

Настройка HTTP-запросов

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

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 для тех областей, которые вам нужны. Области действия для данного метода перечислены на справочной странице. Например, см. страницу метода списка 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);
}