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

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

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

1. Функции API в программах раннего доступа или предварительной версии не представлены в стандартных клиентских библиотеках и могут быть недоступны по умолчанию через HTTP.
2. В любой момент времени в предварительной версии может быть несколько состояний или версий 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. Для общедоступных предварительных версий метка — DEVELOPER_PREVIEW .

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

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_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_ID//rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
  --compressed

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