이 페이지에서는 Google Classroom API에서 요청이 작동하는 방식을 간략히 설명합니다. 이 가이드의 목표는 리소스 중심 설계 또는 Google Workspace API에 아직 익숙하지 않은 독자를 지원하는 것입니다.
특정 코드 샘플은 해당 API 가이드(예: 과정 만들기 및 관리 또는 과정 만들기 및 관리)를 참고하세요.
리소스 중심 디자인
API 구조에 언급된 대로 Classroom API는 리소스 중심 설계 패턴을 따릅니다. 대부분의 리소스에는 리소스 인스턴스 생성, 읽기, 업데이트, 삭제와 같은 표준 작업을 위한 메서드가 있습니다.
예를 들어 API를 사용하여 클래스룸을 create(), patch(), get(), list(), delete() Course할 수 있습니다.
만들기
Course와 같은 새 리소스를 만들려면 상응하는 리소스의 create() 메서드를 호출합니다.
Create() 호출에는 항상 상응하는 리소스의 초기 중요 세부정보가 입력으로 필요합니다. 예를 들어 Course를 만들려면 Course 리소스에서 create() 메서드를 호출하고 요청에 name 및 description를 room와 같은 선택적 정보와 함께 지정합니다.
하위 리소스 (하위 리소스라고도 함)의 경우 상위 리소스의 식별자도 필요합니다. 예를 들어 Course 내에 CourseWork를 생성할 때 Course id는 CourseWork이 속한 Course를 지정해야 합니다.
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()가 성공하면 빈 응답이 반환됩니다.
기타 연산
CourseWork 리소스의 할당자 수정과 같이 앞서 언급한 표준 작업으로는 Classroom API를 사용하여 가능한 모든 작업을 수행할 수 없습니다. 이 경우 modifyAssignees 메서드와 같은 맞춤 메서드를 사용할 수 있습니다. 이러한 메서드의 동작은 맞춤형이며, 각 메서드의 문서를 개별적으로 참조해야 합니다.