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

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

Preview API にアクセスする

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

Stable 版と比較した場合のプレビュー版の機能使用時の 3 つの考慮事項 v1 API の特徴は次のとおりです。

呼び出し元の Google Cloud プロジェクトを Google Workspace に登録する必要がありますデベロッパープレビュープログラムであり、Google によって許可リストに登録されています。
早期アクセスプログラムやプレビュープログラムの API 機能は、 HTTP 経由ではアクセスできない場合もあります。
どの時点においても、複数の API の状態（バージョン）がプレビューします。

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

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

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

動的に生成されるライブラリや Google が提供する静的ライブラリを使用すると、おすすめします。必要に応じて、クライアントライブラリをビルドするをご覧ください。独自のライブラリを構築できます。独自のライブラリの作成は、ありますが、動的ライブラリのセクションをプレビューラベルとその役割を確認します。

動的ライブラリ

Python などの言語のライブラリでは、ランタイムにディスカバリサービスのディスカバリドキュメント。

ディスカバリドキュメントは、Google Cloud リソースに 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 ライブラリを生成し、 preview メソッドを使用すると、適切なサービスで 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 クライアントライブラリを使用するには、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 フィールドを設定します。たとえば、ルーブリックの CRUD Preview 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 MODEL コマンドの呼び出しに 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 リクエスト

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

クライアントライブラリを使用せずに HTTP リクエストを行う場合は、プレビュー機能では、プレビュー版を指定します。これを行うには、label X-Goog-Visibilities ヘッダーと前述のプレビュー版をクエリパラメータまたは POST 本文フィールドのいずれかを指定できます（該当する個々の API をリファレンスドキュメントをご覧ください）。公開プレビューの場合、ラベルは DEVELOPER_PREVIEW です。

たとえば、次の curl リクエストは、ルーブリックサービスに 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 プロジェクトを使用するようにスクリプトを構成する必要があります。デベロッパープレビュープログラムに登録している。
拡張サービスはプレビューメソッドをサポートしていないため、以下を行う必要があります。 HTTP で直接リクエストできます。
上記の説明のように、ラベルとプレビュー版を指定する必要があります。 HTTP セクション。

対応するクイックスタートを参照して、内容を理解してください。基本的なプロジェクトを設定します。その後、これらのプレビュー 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 のセクションで説明されているバージョンが必要です。次の 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);
}