이 페이지에서는 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()과 거의 동일하지만 두 가지 주요 차이점이 있습니다. patch() 메서드를 호출할 때는 다음을 지정해야 합니다.
- 수정할 리소스의
id입니다. - 업데이트할 리소스의 필드를 결정하는 필드 목록(
updateMask)입니다. 기본 필드 집합이 있거나 필드가 추론되는 경우에는 선택사항입니다.
Patch() 메서드는 모든 변경사항이 완료된 API 호출 응답에서 업데이트된 리소스의 전체 인스턴스를 반환합니다.
가져오기 및 나열
리소스를 가져오는 방법에는 get()와 list() 두 가지가 있습니다.
get() 메서드는 식별자를 통해 특정 리소스를 가져옵니다. 예를 들어 id 또는 alias에 따라 Course를 가져옵니다. get() 호출은 전체 리소스를 직접 반환합니다.
list() 메서드는 개별 리소스 식별자 없이 단일 요청에서 동일한 유형의 여러 리소스를 가져옵니다. list() 작업은 종종 일부 상위 리소스의 모든 하위 리소스를 가져옵니다. 예를 들어 Course 내의 모든 CourseWork를 가져옵니다. 이 방법은 여러 get() 호출을 하는 것과 비교하여 요청을 최소화하는 데 유용하며, 특히 원하는 리소스의 id를 모르는 경우에 유용합니다.
일반적으로 list() 메서드에는 단일 호출에서 반환할 수 있는 최대 리소스 양이 있으며 호출에 pageSize 값을 포함하여 하한을 구성할 수 있습니다. 리소스가 한도보다 많은 경우 list() 메서드는 페이지로 나누기를 지원합니다. 반환되는 결과의 각 '페이지'는 다음 리소스 배치를 가져오기 위해 후속 list() 호출에 포함될 수 있는 pageToken를 제공합니다.
삭제
delete() 메서드는 id와 같은 리소스 식별자를 허용하고 해당 리소스를 삭제합니다. delete()이 성공하면 빈 응답이 반환됩니다.
기타 연산
Classroom API로 가능한 모든 작업을 앞서 언급한 표준 작업으로 수행할 수 있는 것은 아닙니다(예: CourseWork 리소스의 할당 대상 수정). 이러한 경우 modifyAssignees 메서드와 같은 맞춤 메서드를 사용할 수 있습니다. 이러한 메서드의 동작은 맞춤형이므로 개별적으로 문서를 참고해야 합니다.