Admin Settings API 개요

Admin Setting API를 사용하면 Google Workspace 도메인 관리자가 Google Data API 피드 형식으로 도메인의 설정을 검색하고 변경할 수 있습니다.

이러한 도메인 설정에는 Google Workspace 관리 콘솔에서 사용할 수 있는 여러 기능이 포함되어 있습니다. 이 API의 사용 예로는 맞춤 제어판 만들기 또는 Google Workspace 도메인을 기존 레거시 환경에 통합하는 것이 있습니다.

Admin Setting API는 Google Data API 프로토콜을 구현합니다. Google Data API는 Atom 게시 프로토콜 (AtomPub) 게시 및 수정 모델을 준수합니다. AtomPub HTTP 요청은 웹 서비스에 RESTful (Representational Set Transfer) 설계 방식을 사용합니다. 자세한 내용은 Google Data API 개발자 가이드를 참고하세요.

잠재고객

이 문서는 Google Workspace 도메인에 관한 정보를 수정하고 검색할 수 있는 클라이언트 애플리케이션을 작성하려는 개발자를 대상으로 합니다. 원시 XML 및 HTTP를 사용하는 기본 Admin Setting API 상호작용의 예를 제공합니다.

이 문서에서는 사용자가 Google Data API 프로토콜의 일반적인 개념을 이해하고 Google Workspace 관리 콘솔에 익숙하다고 가정합니다. 관리 콘솔에 대한 자세한 내용은 관리 콘솔 사용하기를 참고하세요.

시작하기

Admin Setting API를 사용하려면 먼저 계정을 설정하세요.

계정 만들기

Admin Setting API는 Google Workspace 계정에 사용 설정되어 있습니다. 테스트 목적으로 Google Workspace 계정에 가입합니다. Admin Setting 서비스는 Google 계정을 사용하므로 Google Workspace 도메인에 계정이 이미 있다면 모든 설정이 완료된 것입니다.

Admin Setting API 피드 유형 정보

Admin Setting API를 사용하면 다음과 같은 도메인 설정 카테고리를 관리할 수 있습니다.

싱글 사인온(SSO) 설정
SAML 기반 싱글 사인온 (SSO)을 사용하면 사용자가 Google Workspace 호스팅 서비스와 조직 내에서 호스팅할 수 있는 다른 서비스에 동일한 로그인 및 비밀번호를 사용할 수 있습니다. 특히 SSO를 사용하는 경우 Google Workspace와 같은 호스팅 웹 애플리케이션은 사용자가 로그인할 때 사용자를 조직의 ID 공급업체로 리디렉션하여 사용자를 인증합니다. 자세한 내용은 Google Workspace의 SAML 기반 SSO 이해를 참고하세요.

SSO를 구성하려면 Google Workspace 서비스가 사용자의 로그인 정보를 저장하는 ID 공급업체와 통신하는 데 필요한 정보를 입력하고 사용자가 로그인, 로그아웃, 비밀번호 변경을 위해 전송해야 하는 링크를 설정해야 합니다. Admin Setting API를 사용하면 이러한 설정을 프로그래매틱 방식으로 업데이트하고 검색할 수 있습니다. Google은 생성된 공개 키를 사용하여 ID 공급업체에 이 SSO 요청을 확인하고 네트워크 전송 중에 비공개 키 SAML 응답이 수정되지 않았는지 확인합니다.

SSO 설정 사용에 관한 간단한 API별 요약은 ID 공급업체에서 공개 키 인증서를 가져오고, Google에 공개 키를 등록하고, SAML 기반 SSO 쿼리 설정을 설정합니다. 오류 메시지는 SSO 문제 해결을 참고하세요.

  • 키 생성 -- ID 공급업체를 사용하여 DSA 또는 RSA 알고리즘을 사용하여 공개 키와 비공개 키 집합을 생성합니다. 공개 키는 X.509 형식 인증서에 있습니다. SAML 기반 싱글 사인온(SSO) 서명 키에 대한 자세한 내용은 Google Workspace 싱글 사인온(SSO) 서비스의 키 및 인증서 생성을 참고하세요.
  • Google에 등록 -- Admin Setting API의 싱글 사인온(SSO) 설정을 사용하여 공개 키 인증서를 Google에 등록합니다.
  • SSO 설정 -- Admin Setting API의 싱글 사인온(SSO) 설정을 사용하여 도메인의 ID 공급업체 서버와 통신하는 데 사용되는 설정을 구성합니다.

게이트웨이 및 라우팅 설정

이 피드를 사용하면 도메인 관리자가 도메인의 이메일 라우팅을 제어할 수 있습니다.

이메일 라우팅 작업을 통해 관리자는 도메인 수준 이메일 라우팅 설정을 지정할 수 있습니다. 이는 관리 콘솔의 Gmail 설정의 이메일 라우팅 기능과 유사합니다. 자세한 내용은 이메일 라우팅 및 이메일 라우팅 기능의 이중 전송 구성을 참고하세요.

Admin Setting API XML 요청 및 응답 샘플

이 문서에서는 원시 XML 및 HTTP를 사용하는 기본 Admin Setting API 요청 및 응답의 코드 예를 제공합니다. 이 도메인 기본 언어 예에서는 각 작업에 공통적인 요청 및 응답 항목의 본문에 대한 전체 XML 및 HTTP 구문을 보여줍니다.

도메인의 발신 이메일 게이트웨이 설정을 변경하려면 게이트웨이 피드 URL로 HTTP PUT을 전송합니다.

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

도메인 기본 언어 PUT 요청 AtomPub entry XML은 다음과 같습니다.

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
  xmlns:apps='http://schemas.google.com/apps/2006'>
  <apps:property name='smartHost' value='smtp.out.domain.com' />
  <apps:property name='smtpMode' value='SMTP' />
</atom:entry>

작업별 속성 및 값을 제외하고 atom:property 요소는 검색하거나 업데이트하려는 속성에 관한 정보가 포함된 단일 키-값 쌍을 나타냅니다. 이는 모든 Admin Setting API 요청 본문에 공통적입니다.

도메인 기본 언어 응답 entry 요소는 모든 Admin Setting API 응답 본문에 공통적인 XML 구문과 함께 smartHost 및 smtpMode 속성을 반환합니다.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<id>https://apps-apis.google.com/a/feeds/domain/2.0/domainName/email/gateway</id>
<updated>2008-12-17T23:59:23.887Z</updated>
<link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
  2.0/domainName/email/gateway'/>
<link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
  2.0/domainName/email/gateway'/>
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</entry>

싱글 사인온(SSO) 설정 관리

Google Workspace 싱글 사인온 (SSO) 기능을 사용하면 사용자가 로그인 및 비밀번호를 한 번만 입력하면 여러 서비스에 로그인할 수 있습니다. 이 비밀번호는 Google Workspace가 아닌 도메인의 ID 공급업체에서 저장합니다. 자세한 내용은 고객센터의 SSO 페이지를 참고하세요. 다음 섹션에서는 싱글 사인온(SSO) 설정에 사용되는 XML 형식을 보여줍니다.

싱글 사인온(SSO) 설정 검색

싱글 사인온(SSO) 설정을 검색하려면 SSO 일반 피드 URL로 HTTP GET을 전송하고 Authorization 헤더를 Admin Setting 서비스 인증에 설명된 대로 포함합니다. 오류 메시지는 SSO 문제 해결을 참고하세요.

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general

이 작업에는 요청 본문에 매개변수가 없습니다.

응답에 HTTP 200 OK 상태 코드와 도메인의 SSO 설정이 포함된 AtomPub 피드가 반환됩니다.

GET 응답 XML은 samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist, useDomainSpecificIssuer 속성을 반환합니다.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
...
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='true'/>
<apps:property name='ssoWhitelist' value='CIDR formatted IP address'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>

속성은 다음과 같습니다.

samlSignonUri
Google Workspace에서 사용자 인증을 위한 SAML 요청을 전송하는 ID 공급업체의 URL입니다.
samlLogoutUri
사용자가 웹 애플리케이션에서 로그아웃할 때 전송되는 주소입니다.
changePasswordUri
사용자가 웹 애플리케이션의 SSO 비밀번호를 변경하려는 경우 전송되는 주소입니다.
enableSSO
이 도메인에 SAML 기반 SSO를 사용 설정합니다. 이전에 SSO 설정을 구성한 후 enableSSO를 enableSSO=false로 설정한 경우 이전에 입력한 설정은 계속 저장됩니다.
ssoWhitelist
ssoWhitelist는 CIDR (Classless Inter-Domain Routing, 클래스 없는 도메인 간 라우팅) 형식의 네트워크 마스크 IP 주소입니다. ssoWhitelist는 SSO를 사용하여 로그인하는 사용자와 Google Workspace 계정 인증 페이지를 사용하여 로그인하는 사용자를 결정합니다. 마스크가 지정되지 않은 경우 모든 사용자가 SSO를 사용하여 로그인합니다. 자세한 내용은 네트워크 마스크 작동 방식을 참고하세요.
useDomainSpecificIssuer
도메인별 발급기관은 ID 공급업체에 대한 SAML 요청에 사용할 수 있습니다. 대부분의 SSO 배포에는 필요하지 않지만 이 기능은 단일 ID 공급업체를 사용하여 여러 하위 도메인으로 전체 조직을 인증하는 대기업에서 유용합니다. 특정 도메인 발급기관을 지정하면 요청과 연결할 하위 도메인이 결정됩니다. 자세한 내용은 SAML 요청의 발급기관 요소는 어떻게 작동하나요?를 참고하세요.

요청이 어떤 이유로든 실패하면 다른 상태 코드가 반환됩니다. Google Data API 상태 코드에 대한 자세한 내용은 HTTP 상태 코드를 참고하세요.

싱글 사인온(SSO) 설정 업데이트

도메인의 SSO 설정을 업데이트하려면 먼저 싱글 사인온(SSO) 설정 검색 작업을 사용하여 SSO 설정을 검색하고 수정한 후 SSO 피드 URL로 PUT 요청을 전송합니다. 업데이트된 항목의 <id> 값이 기존 항목의 <id>와 정확히 일치하는지 확인합니다. Authorization 헤더를 Admin Setting API 서비스 인증에 설명된 대로 포함합니다. 오류 메시지는 SSO 문제 해결을 참고하세요.

싱글 사인온(SSO) 설정을 업데이트할 때는 SSO 일반 피드 URL로 HTTP PUT을 전송합니다.

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general

PUT 요청의 XML 본문은 다음과 같습니다.

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='enableSSO' value='false' />
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon' />
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout' />
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword' />
<apps:property name='ssoWhitelist' value='127.0.0.1/32' />
<apps:property name='useDomainSpecificIssuer' value='false'/>
</atom:entry>

응답에 HTTP 200 OK 상태 코드와 SSO 설정이 포함된 AtomPub 피드가 반환됩니다.

PUT 응답 XML은 다음과 같습니다.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='false'/>
<apps:property name='ssoWhitelist' value='127.0.0.1/32'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>

요청이 어떤 이유로든 실패하면 다른 상태 코드가 반환됩니다. Google Data API 상태 코드에 대한 자세한 내용은 HTTP 상태 코드를 참고하세요.

대상 고객이 민감한 작업에 복수 사용자 승인 체계를 사용 설정한 경우 싱글 사인온(SSO) 설정을 변경할 수 없습니다. 요청이 errorCode="1811" 및 reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval"로 실패합니다.

싱글 사인온(SSO) 서명 키 검색

싱글 사인온(SSO) 서명 키를 검색하려면 SSO 서명 키 피드 URL로 HTTP GET을 전송하고 Admin Settings service 인증에 설명된 대로 Authorization 헤더를 포함합니다. 오류 메시지는 SSO 문제 해결을 참고하세요.

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

이 작업에는 요청 본문에 매개변수가 없습니다.

응답에 HTTP 200 OK 상태 코드와 서명 키가 포함된 AtomPub 피드가 반환됩니다.

GET 응답 XML은 signingKey 속성을 반환합니다.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</entry>

요청이 어떤 이유로든 실패하면 다른 상태 코드가 반환됩니다. Google Data API 상태 코드에 대한 자세한 내용은 HTTP 상태 코드를 참고하세요.

싱글 사인온(SSO) 서명 키 업데이트

도메인의 SSO 서명 키를 업데이트하려면 먼저 싱글 사인온(SSO) 서명 키 검색 작업을 사용하여 서명 키를 검색하고 수정한 후 SSO 서명 키 피드 URL로 PUT 요청을 전송합니다. 업데이트된 항목의 <id> 값이 기존 항목의 <id>와 정확히 일치하는지 확인합니다. SAML 기반 싱글 사인온(SSO) 서명 키에 대한 자세한 내용은 Google Workspace 싱글 사인온 서비스의 키 및 인증서 생성을 참고하세요.

싱글 사인온(SSO) 서명 키를 업데이트할 때는 SSO 서명 키 피드 URL로 HTTP PUT을 전송합니다.

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

PUT 요청 XML은 다음과 같습니다.

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</atom:entry>

대상 고객이 민감한 작업에 복수 사용자 승인 체계를 사용 설정한 경우 싱글 사인온(SSO) 설정을 변경할 수 없습니다. 요청이 errorCode="1811" 및 reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval"로 실패합니다.

이메일 게이트웨이 및 라우팅 관리

발신 이메일 게이트웨이 섹션에서는 Admin Setting API가 도메인의 사용자로부터 발신 메일의 발신 라우팅을 지원하는 방법을 보여줍니다. 이메일 라우팅 섹션에서는 메일을 다른 메일 서버로 라우팅하는 방법을 보여줍니다.

발신 이메일 게이트웨이 설정 검색

발신 이메일 게이트웨이 설정을 검색하려면 게이트웨이 피드 URL로 HTTP GET을 전송하고 Admin Setting 서비스 인증에 설명된 대로 Authorization 헤더를 포함합니다.

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

이 작업에는 요청 본문에 매개변수가 없습니다.

응답에 HTTP 200 OK 상태 코드와 이메일 게이트웨이 상태 정보가 포함된 AtomPub 피드가 반환됩니다.

GET 응답은 smartHost 및 smtpMode 속성을 반환합니다. 이러한 속성에 대한 자세한 내용은 발신 이메일 게이트웨이 설정 업데이트를 참고하세요.

가능한 응답의 예는 다음과 같습니다.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='smartHost' value='smtpout.domain.com'/>
<apps:property name='smtpMode' value='SMTP'/>
</entry>

요청이 어떤 이유로든 실패하면 다른 상태 코드가 반환됩니다. Google Data API 상태 코드에 대한 자세한 내용은 HTTP 상태 코드를 참고하세요.

발신 이메일 게이트웨이 설정 업데이트

도메인의 발신 이메일 게이트웨이 설정을 업데이트하려면 게이트웨이 피드 URL로 HTTP PUT 요청을 전송합니다.

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

PUT 요청 XML은 다음과 같습니다.

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</atom:entry>

요청 속성은 다음과 같습니다.

smartHost
SMTP 서버의 IP 주소 또는 호스트 이름입니다. Google Workspace는 발신 메일을 이 서버로 라우팅합니다.
smtpMode
기본값은 SMTP입니다. 다른 값인 SMTP_TLS는 메시지를 전송할 때 TLS로 연결을 보호합니다.

응답에 HTTP 200 OK 상태 코드와 이메일 게이트웨이 설정 상태가 포함된 AtomPub 피드가 반환됩니다.

요청이 어떤 이유로든 실패하면 다른 상태 코드가 반환됩니다. Google Data API 상태 코드에 대한 자세한 내용은 HTTP 상태 코드를 참고하세요.

이메일 라우팅 설정 관리

먼저 XML 요청을 만듭니다.

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='routeDestination' value='route-smtp.domain.com'/>
<apps:property name='routeRewriteTo' value='true'/>
<apps:property name='routeEnabled' value='true'/>
<apps:property name='bounceNotifications' value='true'/>
<apps:property name='accountHandling' value='can be either allAccounts | provisionedAccounts | unknownAccounts'/>
</atom:entry>

요청 속성은 다음과 같습니다.

routeDestination
이 대상은 이메일이 라우팅되는 SMTP-In 메일 서버의 호스트 이름 또는 IP 주소입니다. 호스트 이름 또는 IP 주소는 Google에서 확인할 수 있어야 합니다. 메일 호스트 이름 확인에 대한 자세한 내용은 이메일 라우팅으로 Google Workspace 파일럿을 참고하세요.
routeRewriteTo
true이면 메시지의 SMTP 봉투의 to: 필드가 대상 호스트 이름 (user@destination's hostname)으로 변경되고 메시지가 대상 메일 서버의 이 사용자 주소로 전송됩니다. false이면 이메일이 대상 메일 서버의 원래 메시지 to: 이메일 주소 (user@original hostname)로 전송됩니다. 이는 관리 콘솔의 'SMTP 봉투 변경' 설정과 유사합니다. 자세한 내용은 이메일 라우팅의 도메인 설정 을 참고하세요.
routeEnabled
true이면 이메일 라우팅 기능이 사용 설정됩니다. false이면 기능이 사용 중지됩니다.
bounceNotifications
true이면 전송이 실패할 때 Google Workspace에서 발신자에게 반송 알림을 전송할 수 있습니다.
accountHandling
이 설정은 도메인의 다양한 유형의 사용자가 이메일 라우팅의 영향을 받는 방식을 결정합니다.
  • allAccounts -- 모든 이메일을 이 대상으로 전송합니다.
  • provisionedAccounts -- Google Workspace에 사용자가 있는 경우 메일을 이 대상으로 전송합니다.
  • unknownAccounts -- Google Workspace에 사용자가 없는 경우 메일을 이 대상으로 전송합니다. 이는 관리 콘솔의 '전송 이메일' 설정과 유사합니다. 기본 요건 및 메일 라우팅 사용 방법에 대한 자세한 내용은 이메일 라우팅의 도메인 설정을 참고하세요.

이 요청을 게시하려면 이메일 라우팅 피드 URL로 HTTP POST를 전송하고 Authorization 헤더를 Admin Settings 서비스 인증에 설명된 대로 포함합니다.

    https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/emailrouting

응답에 HTTP 200 OK 상태 코드와 보관 정보가 포함된 AtomPub 피드가 반환됩니다.

요청이 어떤 이유로든 실패하면 다른 상태 코드가 반환됩니다. Google Data API 상태 코드에 대한 자세한 내용은 HTTP 상태 코드를 참고하세요.

2018년 10월 31일에 엔드포인트 서비스 종료

이 발표의 일환으로 다음 엔드포인트를 지원 중단했습니다. 2018년 10월 31일에 서비스 종료되었으며 더 이상 사용할 수 없습니다.

  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/defaultLanguage
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/organizationName
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/currentNumberOfUsers
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/maximumNumberOfUsers
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/supportPIN
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/customerPIN
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/adminSecondaryEmail
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/edition
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/creationTime
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/countryCode
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/appearance/customLogo
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/verification/mx