このページでは、Google Classroom API でのリクエストの仕組みについて概要を説明します。目標は、リソース指向の設計や Google Workspace API にまだ慣れていない読者を支援することです。
具体的なコードサンプルについては、コースの作成と管理やコースワークの作成と管理など、対応する API ガイドをご覧ください。
リソース指向の設計
API の構造で説明したように、Classroom API はリソース指向の設計パターンに従います。ほとんどのリソースには、リソースのインスタンスの作成、読み取り、更新、削除などの標準オペレーションのメソッドがあります。
たとえば、API を使用して、Classroom Course で create()、patch()、get()、list()、delete() の操作ができます。
作成
Course などの新しいリソースを作成するには、対応するリソースの create() メソッドを呼び出します。
Create() 呼び出しでは、対応するリソースの初期の重要な詳細情報を常に入力する必要があります。たとえば、Course を作成するには、Course リソースの create() メソッドを呼び出し、リクエストで name と description を指定し、room などのオプション情報を指定します。
サブリソース（子リソース）の場合は、親リソースの識別子も必要です。たとえば、Course 内に CourseWork を作成する場合、CourseWork が属する Course を確立するために Course id が必要です。
Create() メソッドは、API 呼び出しレスポンスで新しく作成されたリソースのインスタンスを返します。通常、返されるリソースには、リソース id や creationTime など、サーバーが生成した追加のフィールドがあります。
パッチ
既存のリソースを変更するには、対応するリソースで patch() メソッド（update() とも呼ばれます）を呼び出します。patch() メソッドは create() とほぼ同じですが、2 つの重要な違いがあります。patch() メソッドを呼び出すときに、次のものを指定する必要があります。
- 変更するリソースの
id。 - リソースのどのフィールドを更新するかを決定するフィールドのリスト（
updateMask）。デフォルトのフィールド セットがある場合や、フィールドが推測される場合、このオプションは省略可能です。
Patch() メソッドは、API 呼び出しレスポンスで更新されたリソースの完全なインスタンスを返し、すべての変更が完了しています。
取得して一覧表示
リソースを取得するためのメソッドとして、get() と list() の 2 つがあります。
get() メソッドは、特定のリソースを識別子で取得します。たとえば、id や alias に基づいて Course を取得します。get() を呼び出すと、リソース全体が直接返されます。
list() メソッドは、個々のリソース識別子を必要とせずに、1 回のリクエストで同じタイプの複数のリソースを取得します。多くの場合、list() オペレーションは親リソースのすべてのサブリソースを取得します。たとえば、Course 内のすべての CourseWork を取得します。これは、複数の get() 呼び出しと比較してリクエストを最小限に抑えるのに役立ちます。また、必要なリソースの id が不明な場合は特に有用です。
一般に、list() メソッドには 1 回の呼び出しで返すことができるリソースの最大量があります。呼び出しに pageSize 値を含めることで、より低い上限を構成できます。上限を超えるリソースがある場合、list() メソッドはページネーションをサポートします。返された結果の各「ページ」で pageToken が提供されます。これを後続の list() 呼び出しに組み込んで、リソースの次のバッチをフェッチします。
削除
delete() メソッドは、id などのリソース ID を受け取り、対応するリソースを削除します。delete() が成功すると、空のレスポンスが返されます。
その他の演算
Classroom API で可能なすべてのオペレーションを、前述の標準オペレーションで実行できるわけではありません。たとえば、CourseWork リソースの割り当て先を変更することはできません。そのような場合は、modifyAssignees メソッドなどのカスタム メソッドを使用できます。これらのメソッドの動作はカスタマイズされているため、ドキュメントを個別に参照する必要があります。