Preview API にアクセスする

このページでは、Classroom API のプレビュー機能にアクセスし、プレビュー版を指定する方法について説明します。

安定版の v1 API と比較して、プレビュー機能を使用する際の考慮事項は次のとおりです。

  1. 早期アクセス プログラムやプレビュー プログラムの API 機能は標準のクライアント ライブラリでは公開されていないため、デフォルトでは HTTP 経由でアクセスできない可能性があります。
  2. プレビュー版では、いつでも複数の API の状態（バージョン）が存在する可能性があります。

クライアント ライブラリでプレビュー機能を有効にする

Classroom API を使用する一般的な方法は、クライアント ライブラリを使用することです。クライアント ライブラリには次の 3 種類があります。

  1. 動的に生成されるクライアント ライブラリ
  2. Google 提供の静的クライアント ライブラリ
  3. 独自のカスタム クライアント ライブラリ

API を使用するには、動的に生成された静的ライブラリまたは Google 提供の静的ライブラリを使用することをおすすめします。独自のライブラリを作成する必要がある場合は、クライアント ライブラリを作成するをご覧ください。独自のライブラリの作成はこのガイドの範囲外ですが、プレビュー ラベルと Discovery での役割については、動的ライブラリのセクションをご覧ください。

動的ライブラリ

Python などの言語のライブラリは、ディスカバリ サービスのディスカバリ ドキュメントを使用して、実行時にクライアント ライブラリを生成します。

ディスカバリ ドキュメントは、REST API を記述して使用するための機械可読仕様です。Google API とやり取りするクライアント ライブラリ、IDE プラグイン、その他のツールの構築に使用されます。1 つのサービスで複数のディスカバリ ドキュメントが提供される場合があります。

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

各言語の詳細については、個々の Google API クライアント ライブラリのドキュメントをご覧ください。

静的ライブラリ

Java、Node.js、PHP、C#、Go などの言語のクライアント ライブラリは、ソースからビルドする必要があります。これらのライブラリはあらかじめ用意されており、プレビュー機能がすでに組み込まれています。

公開プレビューについては、Classroom クライアント ライブラリが他の Workspace デベロッパー プレビュー プログラム クライアント ライブラリに含まれています。限定公開プレビューで静的ライブラリを生成する必要がある場合は、Google の担当者にお問い合わせください。

プレビュー機能がない標準のクライアント ライブラリをインポートするのではなく、これらのローカル ライブラリを使用するには、一般的な依存関係の構成の変更が必要になることがあります。

たとえば、Go クライアント ライブラリを使用するには、go.mod ファイルで replace ディレクティブを使用して、ローカル ディレクトリからのモジュールを要求する必要があります。

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 フィールドを設定します。たとえば、ルーブリック CRUD プレビュー API を使用してルーブリックを作成するには、CREATE リクエストで previewVersion を V1_20231110_PREVIEW に設定します。

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 リクエスト

HTTP で直接 Classroom API を利用することもできます。

クライアント ライブラリを使用せずに HTTP リクエストを行う場合でも、プレビュー機能を有効にしてプレビュー版を指定する必要があります。これを行うには、label に X-Goog-Visibilities ヘッダーを設定し、前述のプレビュー版をクエリ パラメータまたは POST 本文フィールドとして設定します。公開プレビューの場合、ラベルは DEVELOPER_PREVIEW です。

たとえば、次の curl リクエストは、適切な公開設定ラベルとプレビュー版を使用してルーブリック サービスへの LIST 呼び出しを行います。

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

各 HTTP リクエストの API は、REST ドキュメントで説明されています。