이 페이지에서는 Google Classroom API에서 요청이 작동하는 방식을 간략히 설명합니다. 이 가이드의 목표는 리소스 중심 설계 또는 Google Workspace API에 아직 익숙하지 않은 독자를 지원하는 것입니다.
특정 코드 샘플은 해당 API 가이드(예: 과정 만들기 및 관리 또는 과정 만들기 및 관리)를 참고하세요.
리소스 중심 디자인
API 구조에 언급된 대로 Classroom API는 리소스 중심 설계 패턴을 따릅니다. 대부분의 리소스에는 리소스 인스턴스 생성, 읽기, 업데이트, 삭제와 같은 표준 작업을 위한 메서드가 있습니다.
예를 들어 API를 사용하여 클래스룸 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 메서드와 같은 맞춤 메서드를 사용할 수 있습니다. 이러한 메서드의 동작은 맞춤설정되어 있으므로 개별적으로 문서를 참고해야 합니다.