이제 Google 클래스룸 부가기능이 일반적으로 개발자에게 제공됩니다. 자세한 내용은 부가기능 문서를 참고하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

미리보기 API 액세스

이 페이지에서는 Classroom API 미리보기 기능에 액세스하고 미리보기 버전을 지정하는 방법을 설명합니다.

안정적인 v1 API와 비교할 때 미리보기 기능을 사용할 때 고려해야 할 세 가지 사항은 다음과 같습니다.

호출하는 Google Cloud 프로젝트는 Google Workspace 개발자 프리뷰 프로그램에 등록되어 있고 Google에서 허용 목록에 추가되어 있어야 합니다.
사전 체험판 또는 미리보기 프로그램의 API 기능은 표준 클라이언트 라이브러리에 노출되지 않으며, 기본적으로 HTTP를 통해 액세스하지 못할 수 있습니다.
언제든지 미리보기에 여러 API 상태 또는 버전이 있을 수 있습니다.

클라이언트 라이브러리에서 미리보기 기능 사용 설정

클래스룸 API를 사용하는 일반적인 방법은 클라이언트 라이브러리를 사용하는 것입니다. 클라이언트 라이브러리에는 세 가지 유형이 있습니다.

동적으로 생성된 클라이언트 라이브러리
Google에서 제공하는 정적 클라이언트 라이브러리
자체 맞춤 클라이언트 라이브러리

동적으로 생성된 라이브러리 또는 Google에서 제공하는 정적 라이브러리를 사용하는 것이 API를 사용하는 권장 방법입니다. 자체 라이브러리를 빌드해야 하는 경우 클라이언트 라이브러리 빌드를 참고하세요. 자체 라이브러리 만들기는 이 가이드의 범위에 해당하지 않지만 동적 라이브러리 섹션을 검토하여 미리보기 라벨과 디스커버리에서 라벨이 하는 역할에 관해 알아야 합니다.

동적 라이브러리

Python과 같은 언어의 라이브러리는 탐색 서비스의 탐색 문서를 사용하여 런타임 시 클라이언트 라이브러리를 생성합니다.

탐색 문서는 REST API를 설명하고 사용하는 데 참고할 수 있는 머신에서 읽을 수 있는 사양입니다. 또한 클라이언트 라이브러리, IDE 플러그인, Google API와 상호작용하는 기타 도구를 빌드하는 데 사용됩니다. 하나의 서비스는 여러 개의 탐색 문서를 제공할 수 있습니다.

Classroom API 서비스 (classroom.googleapis.com)의 탐색 문서는 다음 엔드포인트에서 확인할 수 있습니다.

https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY

미리보기 API를 사용할 때 중요한 구분은 적절한 label를 지정하는 것입니다. 클래스룸 공개 미리보기의 경우 이 라벨은 DEVELOPER_PREVIEW입니다.

Python 라이브러리를 생성하고 미리보기 메서드로 클래스룸 서비스를 인스턴스화하려면 적절한 서비스, 사용자 인증 정보, 라벨을 사용하여 검색 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와 같은 언어의 클라이언트 라이브러리는 소스에서 빌드해야 합니다. 이러한 라이브러리는 자동으로 제공되며 미리보기 기능이 이미 통합되어 있습니다.

공개 미리보기의 경우 클래스룸 클라이언트 라이브러리는 다른 Workspace 개발자 프리뷰 프로그램 클라이언트 라이브러리와 함께 확인할 수 있습니다. 비공개 미리보기의 경우 정적 라이브러리를 생성해야 하는 경우 Google 담당자에게 문의하세요.

미리보기 기능이 없는 표준 클라이언트 라이브러리를 가져오는 대신 이러한 로컬 라이브러리를 사용하려면 일반적인 종속 항목 구성을 수정해야 할 수 있습니다.

예를 들어 Go 클라이언트 라이브러리를 사용하려면 go.mod 파일에서 replace 지시어를 사용하여 로컬 디렉터리의 모듈을 가져와야 합니다.

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 필드를 설정합니다. 예를 들어 Rubrics CRUD 미리보기 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 호출의 응답에는 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 요청

HTTP를 사용하여 Classroom API를 직접 사용할 수도 있습니다.

클라이언트 라이브러리 없이 HTTP 요청을 실행하는 경우에도 미리보기 기능을 사용 설정하고 미리보기 버전을 지정해야 합니다. X-Goog-Visibilities 헤더와 위에서 언급한 미리보기 버전을 쿼리 매개변수 또는 POST 본문 필드로 사용하여 label를 설정하면 됩니다 (해당하는 개별 API 참조 문서 참고). 공개 미리보기의 경우 라벨은 DEVELOPER_PREVIEW입니다.

예를 들어 다음 curl 요청은 적절한 공개 상태 라벨 및 미리보기 버전을 사용하여 Rubrics 서비스에 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 섹션에 설명된 대로 라벨과 미리보기 버전을 제공해야 합니다.

Apps Script에 익숙해지고 기본 프로젝트를 설정하려면 해당 빠른 시작을 참조하세요. 그런 다음 다음 안내에 따라 미리보기 API 호출을 시작합니다.

스크립트에서 사용하는 Cloud 프로젝트 변경

프로젝트 설정에서 프로젝트 변경을 클릭하고 개발자 미리보기 프로그램에 등록한 프로젝트의 Cloud 프로젝트 ID를 입력합니다 (기본적으로 Apps Script 스크립트는 일반 프로젝트를 사용함). 등록된 프로젝트만 미리보기 메서드를 호출할 수 있습니다.

HTTP 요청 구성

그런 다음 편집기에서 콜백할 메서드의 HTTP 요청을 구성합니다. 예를 들어 빠른 시작에서 클래스룸 서비스를 사용하여 과정을 나열하면 다음과 같이 표시됩니다.

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를 호출하려면 적절한 범위를 수동으로 추가해야 합니다.

Project Settings(프로젝트 설정)에서 Show 'appsscript.json' manifest file in editor(편집기에 'appsscript.json' 매니페스트 파일 표시)를 사용 설정합니다. 편집기로 돌아가서 필요한 범위의 appscript.json 파일에 oauthScopes를 추가합니다. 특정 메서드의 범위는 참조 페이지에 나열되어 있습니다. 예를 들어 courses.courseWork.rubrics list method 페이지를 참고하세요.

업데이트된 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 섹션에 설명된 대로 적절한 라벨과 미리보기 버전을 추가했는지 확인합니다. Rubrics 서비스에 대한 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);
}