Google Cloud 프로젝트 구성

이 페이지에는 클래스룸 부가기능용 Google Cloud 프로젝트를 만들고 구성하는 데 필요한 정보가 포함되어 있습니다. Google Cloud 프로젝트는 OAuth 2.0(Google SSO)을 통해 Google 싱글 사인온을 구현하고, 부가기능에서 수행한 요청을 승인하고, Google Workspace Marketplace 스토어에서 부가기능의 등록정보를 관리하는 데 사용됩니다.

부가기능을 마켓에 게시하는 방법에 관한 일반적인 내용은 앱 게시를 참고하세요.

Google Cloud 프로젝트 생성

핵심사항: 프로덕션 부가기능 애플리케이션의 공개 상태가 Google Workspace Marketplace SDK에서 공개로 설정되어 있어야 합니다. 비공개 프로젝트는 부가기능을 개발하고 테스트하는 데 유용하지만 공개 프로젝트만 필요합니다.

개발에 사용되는 비공개 프로젝트와 최종 사용자가 액세스할 수 있는 공개 프로젝트의 두 가지 유형의 프로젝트를 만들 수 있습니다. '공개' 및 '비공개' 라벨은 Google Workspace Marketplace에서 애플리케이션의 공개 상태를 나타냅니다. 비공개 Marketplace 애플리케이션은 생성된 도메인 내의 사용자만 설치할 수 있는 반면, 공개 Marketplace 애플리케이션은 모든 Google Workspace 도메인에서 사용할 수 있습니다. 프로젝트는 공개와 비공개로 동시에 설정할 수 없으므로 두 개의 별도 애플리케이션이어야 합니다. 공개 애플리케이션은 Marketplace에서 제공되기 전에 검토 및 승인을 받아야 합니다.

중요: 비공개 프로젝트를 공개 프로젝트로 전환할 수 없습니다.

일반적인 Google Cloud 프로젝트 생성 정보는 Google Cloud 프로젝트 만들기를 참고하세요.

공개 Google Cloud 프로젝트 만들기

이 프로젝트는 관리자, 교사, 학생이 액세스할 수 있는 부가기능 애플리케이션을 나타냅니다. 공개 프로젝트는 출시하거나 설치하기 전에 Google Workspace Marketplace팀에서 검토하고 승인해야 합니다.

1. 프로덕션 도메인에 새 Google Cloud 프로젝트를 만듭니다.

   Google Cloud 프로젝트 만들기

   중요: 프로젝트가 프로덕션 도메인에 속하고 해당 도메인의 사용자로 Google Cloud 콘솔에 로그인했는지 확인합니다.
   경고: 테스트에는 프로젝트의 초안 버전을 사용해야 합니다. 자세한 내용은 임시 파일로 앱 등록정보 업데이트하기를 참고하세요.

2. Cloud 프로젝트에서 Classroom API를 사용 설정합니다.

   Classroom API 사용 설정

3. Cloud 프로젝트에서 Google Workspace Marketplace SDK를 사용 설정합니다.

   Google Workspace Marketplace SDK 사용 설정하기

4. Marketplace SDK 앱 구성 앱 공개 상태를 공개로 설정하고 미등록 체크박스를 선택합니다.

   요점: 내부 개발 및 테스트 중에 사용된 비공개 프로젝트는 공유하거나 변환할 수 없습니다.
   요점: 일부 공개 앱은 탐색하거나 검색해도 Google Workspace Marketplace에서 찾을 수 없습니다. Marketplace SDK 구성 내에서 부가기능을 설치하는 데 사용할 수 있는 직접 URL을 확인할 수 있습니다. Google과 개발자만 스토어 등록정보를 찾을 수 있습니다. 일반 대중에게 출시하기 전까지는 앱을 미등록 상태로 유지해야 합니다. 부가기능이 Marketplace SDK의 앱 구성 페이지에 표시되는지 여부를 전환할 수 있습니다.

5. Marketplace SDK의 스토어 등록정보 페이지에서 필수 입력란을 작성하고 게시를 클릭합니다.

6. 앱은 Google Workspace Marketplace팀에서 검토합니다. Google에서는 Marketplace SDK에 지정된 개발자 이메일 주소를 사용하여 연락합니다. 앱이 승인되면 교사와 관리자가 Marketplace에서 앱을 찾을 수 있도록 미등록 체크박스를 선택 해제합니다.

비공개 Google Cloud 프로젝트 만들기

이 비공개 프로젝트는 개발에 사용되는 부가기능 애플리케이션을 나타냅니다. 이 앱은 생성된 도메인 외부의 사용자가 액세스할 수 없지만 설치 전에 승인을 받을 필요는 없습니다. 따라서 Google에서는 이 프로젝트를 사용하여 통제된 환경에서 부가기능을 개발하고 테스트하는 것을 권장합니다.

비공개 프로젝트를 만들려면 Teaching & Learning 또는 Plus 라이선스가 있는 Google Workspace for Education 도메인에 액세스할 수 있어야 합니다. 이러한 도메인에 아직 액세스할 수 없는 경우 다음 단계에 따라 Google Workspace for Education 데모 도메인을 설정하고, Plus 라이선스로 업그레이드하고, 클래스룸 부가기능 API에 액세스하도록 허용하세요.

1. 개발자 테스트 도메인을 가져오는 단계를 완료합니다.

2. 데모 도메인에서 관리자로 로그인한 상태에서 새 Google Cloud 프로젝트를 만듭니다.

   Google Cloud 프로젝트 만들기

   경고: 프로젝트가 데모 도메인에 속해 있고 데모 도메인의 관리자 계정을 사용하여 Google Cloud 콘솔에 로그인했는지 확인하세요.

   Google Cloud 콘솔에 액세스하거나 Cloud 프로젝트를 만들 수 없는 경우 관리 콘솔에서 다음을 확인하세요.

   • 계정 설정 > 연령별 액세스 설정 페이지로 이동하여 이 그룹 또는 조직 단위의 모든 사용자가 만 18세 이상임 옵션을 선택합니다.
   • 앱 > 추가 Google 서비스에서 다음을 수행합니다.
   • Google Cloud Platform이 모든 사용자에게 사용 설정되어 있습니다.
   • 프로젝트 생성 설정이 사용자가 프로젝트를 만들 수 있도록 허용입니다.
   • Cloud Shell 액세스 설정이 Cloud Shell에 대한 액세스 허용입니다.

3. 데모 도메인 업그레이드 요청 양식을 작성하여 제출합니다. 이 양식을 제출하면 Google에 데모 도메인을 라이선스 10개가 포함된 Google Workspace for Education Plus로 업그레이드해 달라고 요청하고 Cloud 프로젝트를 클래스룸 부가기능 API에 허용할 수 있습니다.

   업그레이드 및 허용 목록 프로세스가 완료되면 이메일이 전송됩니다. 관리 콘솔에서 테스트 교사 계정에 Plus 라이선스를 할당합니다. 디렉터리 > 사용자에서 테스트 교사 계정을 만들거나 선택합니다. 각 교사의 라이선스에서 Google Workspace for Education Plus가 할당됨으로 표시되는지 확인합니다.

4. Cloud 프로젝트에서 Classroom API를 사용 설정합니다.

   Classroom API 사용 설정

5. Cloud 프로젝트에서 Google Workspace Marketplace SDK를 사용 설정합니다.

   Google Workspace Marketplace SDK 사용 설정하기

6. Marketplace SDK 앱 구성 앱 공개 상태를 비공개로 설정합니다.

7. Marketplace SDK의 스토어 등록정보 페이지에서 필수 입력란을 작성하고 게시를 클릭합니다. 앱 등록정보가 게시되면 도메인의 사용자가 Google Workspace Marketplace에서 앱을 찾고 설치하거나 스토어 등록정보 페이지에 표시된 앱 URL을 방문하여 앱을 설치할 수 있습니다.

OAuth 2.0

클래스룸 API에 액세스하려면 사용자 데이터 액세스 동의가 필요합니다. 이러한 값은 로그인한 사용자에 대해 OAuth 범위에 대한 Google 액세스를 요청하고 이후 Google Classroom에 API 호출을 하는 데 사용할 수 있는 토큰을 수신하여 획득합니다. 도메인 관리자가 부가기능을 설치하는 경우 도메인 사용자를 대신하여 동의할 수 있도록 Google Workspace Marketplace 스토어 등록정보에서 범위를 구성해야 합니다.

중요: 부가기능에서 추가 범위를 요청하는 경우 OAuth 동의 화면, Marketplace SDK 앱 구성 탭, 및 부가기능의 애플리케이션 코드에 포함하세요. 이러한 위치의 범위가 일치하지 않으면 부가기능 설치 중에 사용자에게 문제가 발생할 수 있습니다.

클래스룸 범위는 민감하므로 부가기능을 출시하기 전에 OAuth 인증을 요청해야 합니다. 그렇지 않으면 사용자에게 애플리케이션이 인증되지 않았다는 경고 메시지가 표시되며 소수의 사용자만 제품에 액세스할 수 있습니다. 인증에 대한 자세한 내용은 검토 순서 개요를 참고하세요.

경고: 기존 Google Cloud 프로젝트를 사용하여 부가기능을 개발하는 경우 인증이 완료될 때까지 기존 제품의 코드에서 새 범위를 요청하지 마세요. 별도의 승인 흐름이나 테스트 환경을 사용하거나, 인증을 완료하기 전에 부가기능 관련 경로에 대해서만 이러한 범위를 요청하도록 기능 플래그를 설정하세요.

사용 가능한 모든 범위와 용도의 자세한 목록은 Google API용 OAuth 범위 페이지를 참고하세요. 일반적인 OAuth 구성 정보는 Workspace 문서의 OAuth 구성 페이지를 참고하세요.

사용자 권한

웹 앱은 다음 범위 중 하나 이상을 요청해야 합니다.

• https://www.googleapis.com/auth/userinfo.email: 애플리케이션이 사용자의 이메일 주소를 볼 수 있도록 허용합니다.
• https://www.googleapis.com/auth/userinfo.profile: 애플리케이션이 초상화, 성과 이름, 사용자가 공개적으로 제공한 기타 개인 정보와 같은 개인 정보를 볼 수 있습니다.

사용자가 부가기능에서 이러한 범위 중 하나를 승인하면 login_hint 쿼리 매개변수로 식별됩니다. 이 매개변수는 iframe이 열릴 때 웹 앱의 URL에 전달됩니다. 사용자가 이러한 범위 중 하나를 승인하지 않은 경우 login_hint가 전송되지 않습니다.

경고: 동일한 사용자가 후속 방문에서 login_hint를 수신하려면 앱이 userinfo.email 또는 userinfo.profile 범위 중 하나 이상을 요청해야 합니다.

login_hint는 Google 로그인을 사용하거나 OAuth 토큰을 요청할 때 선택적으로 Google에 전달할 수 있는 표준 OpenID Connect 매개변수입니다. 이는 최종 사용자의 승인 환경을 더 원활하게 만들기 위한 것입니다.

클래스룸 부가기능 범위

다음 범위는 클래스룸 부가기능에만 해당합니다.

• 모든 API 메서드에 액세스할 수 있는 https://www.googleapis.com/auth/classroom.addons.teacher
• https://www.googleapis.com/auth/classroom.addons.student: 확인 실행 및 첨부파일 읽기 작업에 액세스할 수 있습니다.

사용자의 사용자 인증 정보를 나타내는 유효한 OAuth 액세스 토큰이 있더라도 API 호출은 다음과 같은 추가 요구사항에 의해 제한됩니다.

• 모든 메서드에는 사용자가 요청의 courseId로 지정된 수업의 교사 또는 학생이어야 합니다.
• 첨부파일 생성, 업데이트, 삭제, 성적 전달에는 사용자가 교사여야 합니다.
• 특정 Google 클래스룸 게시물에 대한 호출은 다음 검사에 의해 제한됩니다.
  • 애드온에 게시물에 첨부파일이 하나 이상 이미 있는 경우 다음을 요청할 수 있습니다.
    • iframe 실행 유효성 검사
    • 첨부파일 읽기, 업데이트, 삭제 작업
    • 게시물의 성적 업데이트
  • 첨부파일 검색 iframe이 처음 열릴 때 부가기능에 아직 게시물에 첨부파일이 없을 수 있습니다. 다음 항목을 요청하는 데 사용할 수 있는 addOnToken 쿼리 매개변수가 제공됩니다.
    • 게시물 아래에 첨부파일 만들기 (addOnToken 필요)
    • 실행 유효성 검사 (제공된 경우 addOnToken가 검사되며, 게시물에 기존 첨부파일이 없는 경우 필요함)

OAuth 확인

참고: OAuth 인증 프로세스의 일부로 제출할 데모 동영상을 만들 수 없습니다. 대신 OAuth를 확인하지 않고 부가기능을 게시하세요. 이렇게 하면 Google Workspace Marketplace 검토팀에 데모 동영상을 대신 만들어 달라는 알림이 전송됩니다. 그러면 검토팀에서 동영상을 제공하므로 OAuth 인증 제출에 동영상을 포함할 수 있습니다.

클래스룸 부가기능은 Google API를 사용하여 Google 사용자의 데이터에 액세스합니다.

• 브랜드 아이덴티티를 확인합니다.
• 민감한 OAuth 범위 확인

인증 절차에 관한 자세한 내용은 OAuth API 인증 FAQ를 참고하세요.

Google Workspace Marketplace 등록정보

경고: 게시 과정에서 공개 상태 옵션을 저장한 후에는 나중에 선택사항을 변경할 수 없습니다.

일반적인 Google Workspace Marketplace SDK 구성 정보는 Google Workspace Marketplace SDK 사용 설정 및 구성하기 및 Google Workspace Marketplace 스토어 등록정보 만들기를 참고하세요.

등록정보 고려사항

공개 Google Cloud 프로젝트의 Marketplace SDK 스토어 등록정보는 최종 사용자에게 표시되는 애플리케이션 이름과 설명을 지정합니다. 앱 세부정보에서 여러 언어로 이러한 세부정보를 제공할 수 있습니다.

등록정보에서 다음 가이드라인을 따르세요.

• 앱 세부정보에서 다음을 수행합니다.
  • 애플리케이션 이름에 문장 부호를 사용하지 마세요. 예를 들어 'My Company: My Add-on' 또는 'My Add-on, by My Company' 대신 'My Add-on by My Company'를 사용합니다.
  • 간략한 설명과 상세한 설명에 동일한 텍스트가 포함되어서는 안 됩니다.
  • 가격 필드의 값을 선택했는지 확인합니다. 이 필드에는 무료, 무료 체험판으로 결제됨, 무료 기능으로 결제됨, 유료 가격 옵션이 포함됩니다. 마켓 목록에서 비용 금액을 지정할 필요가 없습니다.
  • 카테고리 필드의 값을 선택했는지 확인합니다. 학술 리소스 또는 교사 및 관리자 도구가 클래스룸 부가기능에 적합할 수 있습니다.
  • 자세한 내용은 Marketplace의 앱 세부정보 설명에 나열된 항목을 참고하세요.

중요: 부가기능을 제공하는 각 언어의 앱 세부정보를 확인하세요.

• 그래픽 애셋에서 다음을 수행합니다.
  • 제공된 그래픽 애셋이 흐리지 않고 Google Workspace Marketplace 표준에 지정된 크기를 충족합니다.
  • 제공된 스크린샷은 부가기능 환경을 정확하게 나타냅니다.
• 지원 링크에서 다음을 확인합니다.
  • 애플리케이션의 서비스 약관 링크를 제공했는지 확인합니다.
• 허용되는 이름과 설명을 다루는 Google API 브랜딩 가이드라인을 준수해야 합니다.
• 등록정보에서 Google 제품을 언급하는 경우 상표 목록에 제공된 형식으로 이름을 사용하세요. 지정된 경우 상표 (™) 기호를 포함해야 합니다. 'Google Docs'가 아닌 'Google Docs™'를 사용하세요.

Google의 라이선스 및 결제 서비스와 통합

Google Workspace Marketplace 애플리케이션을 Google의 라이선스 및 결제 서비스와 통합하는 데 관심이 있다면 Marketplace API를 참고하세요.

설치 설정

부가기능은 관리자 설치 외에 개별 설치를 허용할 수 있습니다. 이 페이지에서는 두 설치 유형 간의 차이점을 설명하며, 특정 설치 유형을 홍보하기 위한 것이 아닙니다. Google Workspace Marketplace SDK 앱 구성 페이지에서 개별 설치를 허용할지 선택할 수 있습니다.

관리자 설치

관리자 설치를 사용하면 관리자가 도메인의 모든 계정 또는 특정 액세스 그룹이나 조직 단위에 부가기능을 추가할 수 있습니다. 도메인 관리자만 관리자 설치를 실행할 수 있습니다. 관리자는 선택적으로 도메인의 모든 사용자를 대신하여 모든 액세스 범위에 동의할 수 있습니다. 관리자가 동의하는 경우 사용자에게 액세스 범위에 동의하라는 메시지가 표시되지 않습니다.

다음은 관리자 설치와 관련된 몇 가지 고려사항입니다.

• 더 엄격한 관리. 관리자는 애드온에 액세스할 수 있는 사용자를 제한할 수 있습니다.
• 라이선스와의 호환성. 애플리케이션에 라이선스가 필요한 경우 관리자를 통해 설치를 전달하면 라이선스가 해당 기관에 적절하게 배포되고 사용되도록 하는 데 도움이 될 수 있습니다.
• 최종 사용자의 부담 감소 관리자 설치는 교사와 학생의 설정 부담을 줄여줍니다. 이렇게 하면 클릭수가 줄어들고 혼란을 야기할 가능성이 줄어들어 사용자 환경이 더 원활해질 수 있습니다.

관리자 설치를 실행하는 방법은 도메인에 Marketplace 앱 설치하기를 참고하고 조직 구조 작동 방식에서 조직 단위 및 액세스 그룹에 대해 자세히 알아보세요.

개별 설치

개별 설치는 사용자의 계정에 부가기능을 추가합니다. 설치 중에 사용자에게 애드온의 액세스 범위에 동의하라는 메시지가 표시됩니다.

다음은 개별 설치와 관련된 몇 가지 고려사항입니다.

• 채택 촉진 더 많은 사용자가 Google Workspace Marketplace에서 부가기능을 보고 설치할 수 있습니다. 개별 설치를 허용하면 더 많은 교사가 제품을 채택하거나 옹호할 수 있습니다.
• 관리자 테스트. 관리자는 더 큰 그룹에 부가기능을 승인하거나 설치하기 전에 테스트하거나 평가하기 위해 부가기능을 개별적으로 설치할 수 있습니다.

관리자는 사용자를 대신하여 부가기능을 설치하는 것 외에도 사용자가 개별 설치를 허용하는 부가기능을 설치할 수 있도록 허용 목록을 유지할 수 있습니다. 부가기능이 허용 목록에 없으면 사용자는 Google Workspace Marketplace에서 부가기능의 등록정보를 계속 볼 수 있지만 부가기능을 설치할 수는 없습니다. 대신 도메인 관리자가 부가기능의 설치를 허용하지 않았다는 메시지가 표시됩니다. 이 동작에 대해 자세히 알아보려면 허용 목록에서 Google Workspace Marketplace 앱 관리하기를 참고하세요.

자세한 내용은 Google Workspace Marketplace 설치 설정 문서를 참고하세요.

앱 통합

첨부파일 설정 URI 필드에 실행 iframe URL을 제공해야 합니다. 이 URL은 첨부파일 검색 iframe의 iframe src 값으로 사용됩니다. 첨부파일 검색 iframe은 교사가 과제에 첨부할 콘텐츠나 활동을 찾는 데 사용됩니다. Google Cloud 프로젝트 콘솔에서 설정할 수 있습니다.

허용된 첨부파일 URI 접두사는 *.addOnAttachments.create 및 *.addOnAttachments.patch 메서드를 사용하여 AddOnAttachment에 설정된 URI를 검증하는 데 사용됩니다. 유효성 검사는 리터럴 문자열 접두사 일치이며 와일드 카드 사용은 허용되지 않습니다.

부가기능에서 첨부파일이 허용되는 모든 URI 접두사도 지정해야 합니다. 이 기능은 승인되지 않은 소스의 첨부파일을 방지하여 보안을 강화합니다.

Google Cloud 프로젝트의 Marketplace SDK 앱 구성 페이지에서 이 두 값을 모두 설정합니다.

테스트 계정

데모 도메인에서 테스트 계정을 만들어 비공개 부가기능의 올바른 동작을 확인합니다. 학생 작업 검토 iframe에서 학생 간 전환을 테스트하려면 학생 계정 2개가 필요합니다.

추천 테스트 계정:

• 교사 태미, tammy.teacher@<your demo domain>
• 학생 샘, sam.student@<your demo domain>
• Sally Student, sally.student@<your demo domain>

다음 절차에 따라 새 테스트 계정을 만드세요.

1. 관리 콘솔에 로그인합니다.
2. 사용자로 이동합니다.
3. 새 사용자 추가를 클릭합니다 (그림 1 참고).
4. 사용자 정보를 입력하고 적절한 역할을 할당합니다.

그림 1. 관리 콘솔 내 새 사용자 추가 링크의 위치

다음 절차에 따라 새 테스트 그룹을 만드세요.

1. 관리 콘솔에 로그인합니다.
2. 그룹으로 이동합니다.
3. 그룹 만들기를 클릭합니다 (그림 2 참고).
4. 그룹의 회원과 소유자를 입력합니다.

그림 2. 관리 콘솔 내 그룹 만들기 링크의 위치