Google Classroom アドオンの一般提供が開始されました。詳しくは、アドオンのドキュメントをご覧ください。

このページは Cloud Translation API によって翻訳されました。

Preview API にアクセスする

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

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

呼び出し元の Google Cloud プロジェクトは、Google Workspace デベロッパープレビュープログラムに登録され、Google によって許可リストに登録されている必要があります。
早期アクセスプログラムまたはプレビュープログラムの API 機能は、標準のクライアントライブラリでは公開されず、デフォルトでは HTTP 経由でアクセスできない場合があります。
特定の時点で、複数の API 状態またはバージョンがプレビュー版として提供されている場合があります。

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

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

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

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

動的ライブラリ

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

ディスカバリドキュメントは、REST API を記述して使用するための機械可読仕様です。クライアントライブラリ、IDE プラグイン、Google API と連携するその他のツールのビルドに使用されます。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 サービスをインスタンス化するには、適切なサービス、認証情報、ラベルを使用して Discovery 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 フィールドを設定します。たとえば、Rubrics 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 リクエストを行う場合でも、プレビュー機能を有効にしてプレビューバージョンを指定する必要があります。これを行うには、X-Goog-Visibilities ヘッダーと前述のプレビューバージョンをクエリパラメータまたは POST 本文フィールドとして指定して label を設定します（該当する個々の API リファレンスドキュメントを参照）。公開プレビューの場合、ラベルは DEVELOPER_PREVIEW です。

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

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

各 HTTP リクエストの API については、REST ドキュメントをご覧ください。

Google Apps Script

Google Apps Script からプレビュー API を呼び出すことができます。ただし、一般的な Apps Script の使用方法とは異なる点がいくつかあります。

デベロッパープレビュープログラムに登録した Google Cloud プロジェクトを使用するようにスクリプトを構成する必要があります。
Advanced Services はプレビュー版のメソッドをサポートしていないため、HTTP でリクエストを直接行う必要があります。
前の HTTP セクションで説明したように、ラベルとプレビューバージョンを指定する必要があります。

対応するクイックスタートを参照して、Apps Script に慣れ、基本的なプロジェクトを設定します。プレビュー API の呼び出しを開始するには、次の手順に沿って操作します。

スクリプトで使用される Cloud プロジェクトを変更する

[プロジェクトの設定] で [プロジェクトを変更] をクリックし、デベロッパープレビュープログラムに登録したプロジェクトの Cloud プロジェクト ID を入力します（デフォルトでは、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 スコープが推測されますが、Apps Script で Google API に直接 HTTP 呼び出しを行うには、適切なスコープを手動で追加する必要があります。

[プロジェクトの設定] で、[「appsscript.json」マニフェストファイルをエディタで表示する] を有効にします。エディタに戻り、必要なスコープの appscript.json ファイルに oauthScopes を追加します。特定の方法のスコープは、リファレンスページに一覧表示されます。たとえば、courses.courseWork.rubrics list メソッドのページをご覧ください。

更新された 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 セクションで説明したように、適切なラベルとプレビューバージョンを追加したことを確認します。Rubrics サービスへの LIST 呼び出しの例は次のようになります。

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