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 提供の静的ライブラリを使用することをおすすめします。独自のライブラリをビルドする必要がある場合は、クライアントライブラリをビルドするをご覧ください。独自のライブラリの作成は、このガイドの範囲外ですが、動的ライブラリのセクションで、プレビューラベルとファインドでのその役割について確認してください。

動的ライブラリ

Python などの言語のライブラリは、Discovery Service の Discovery ドキュメントを使用して、実行時にクライアントライブラリを生成します。

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

Classroom API サービス（classroom.googleapis.com）の Discovery ドキュメントは、次のエンドポイントで確認できます。

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 フィールドを設定します。たとえば、Rubricas 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 リストメソッドのページをご覧ください。

更新された 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);
}