사용자 계정 관리

Directory API는 사용자를 생성, 업데이트, 삭제하는 프로그래매틱 메서드를 제공합니다. 개별 사용자에 대한 정보 또는 지정된 기준을 충족하는 사용자 목록을 가져올 수도 있습니다. 다음은 몇 가지 기본 사용자 작업의 예입니다.

사용자 계정 만들기

Google Workspace 계정의 도메인에 사용자 계정을 추가할 수 있습니다. 사용자 계정을 추가하기 전에 도메인 소유권을 확인합니다.

개인 Gmail 계정을 자체 도메인 이름이 있는 비즈니스 이메일 계정으로 업그레이드한 경우 추가 Google Workspace 설정을 잠금 해제할 때까지 새 사용자 계정을 만들 수 없습니다. 자세한 내용은 G Suite 비즈니스 이메일 계정이 G Suite Basic으로 업데이트됨을 참고하세요.

도메인 중 하나를 사용하여 사용자 계정을 만들려면 다음 POST 요청을 사용하고 인증 및 승인 알아보기에 설명된 승인을 포함합니다. OAuth 2.0 범위 목록에서 Directory API에 사용할 수 있는 범위를 확인할 수 있습니다. 요청 쿼리 문자열 속성은 users.insert() 메서드를 참고하세요. 

POST https://admin.googleapis.com/admin/directory/v1/users

모든 생성 요청에는 요청을 처리하는 데 필요한 정보를 제출해야 합니다. 클라이언트 라이브러리를 사용하는 경우 선택한 언어의 데이터 객체를 JSON 데이터 형식의 객체로 변환합니다.

JSON 요청

다음 JSON은 사용자를 만드는 샘플 요청을 보여줍니다. 요청 및 응답 속성의 전체 목록은 API 참조를 확인하세요. 

{
"primaryEmail": "[email protected]",
"name": {
 "givenName": "Elizabeth",
 "familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
 {
  "type": "work",
  "protocol": "gtalk",
  "im": "[email protected]",
  "primary": true
 }
],
"emails": [
 {
  "address": "[email protected]",
  "type": "home",
  "customType": "",
  "primary": true
 }
],
"addresses": [
 {
  "type": "work",
  "customType": "",
  "streetAddress": "1600 Amphitheatre Parkway",
  "locality": "Mountain View",
  "region": "CA",
  "postalCode": "94043"
 }
],
"externalIds": [
 {
  "value": "12345",
  "type": "custom",
  "customType": "employee"
 }
],
"organizations": [
 {
  "name": "Google Inc.",
  "title": "SWE",
  "primary": true,
  "type": "work",
  "description": "Software engineer"
 }
],
"phones": [
 {
  "value": "+1 nnn nnn nnnn",
  "type": "work"
 }
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}

생성 요청의 쿼리 빈도가 너무 높으면 할당량이 초과되었음을 나타내는 HTTP 503 응답이 API 서버에서 수신될 수 있습니다. 이러한 응답을 받으면 지수 백오프 알고리즘을 사용하여 요청을 다시 시도합니다.

새 계정과 관련하여 알아야 할 사항은 다음과 같습니다.

  • Google 계정에서 메일 라이선스를 구매한 경우 새 사용자 계정에 자동으로 메일함이 할당됩니다. 이 과제를 완료하고 활성화하는 데 몇 분 정도 걸릴 수 있습니다.
  • 요청에서 읽기 전용 필드(예: isAdmin)를 수정하면 API 서비스에서 자동으로 무시됩니다.
  • 계정에서 허용되는 최대 도메인 수는 600개 (기본 도메인 1개 + 추가 도메인 599개)입니다.
  • 사용자 계정이 생성될 때 사용자가 특정 조직 단위에 할당되지 않은 경우 계정이 최상위 조직 단위에 있습니다. 사용자가 액세스할 수 있는 Google Workspace 서비스는 사용자의 조직 단위에 따라 결정됩니다. 사용자가 새 조직으로 이동하면 사용자의 액세스 권한이 변경됩니다. 조직 구조에 대한 자세한 내용은 관리 고객센터를 참고하세요. 사용자를 다른 조직으로 이동하는 방법에 관한 자세한 내용은 사용자 업데이트를 참고하세요.
  • 새 사용자 계정에는 password가 필요합니다. hashFunction가 지정된 경우 비밀번호가 유효한 해시 키여야 합니다. 지정되지 않은 경우 비밀번호는 일반 텍스트여야 하며 8~100자 사이의 ASCII 문자로 구성되어야 합니다. 자세한 내용은 API 참조를 참고하세요.
  • Google Workspace의 유연한 요금제를 사용하는 사용자의 경우 이 API를 사용하여 사용자를 만들면 금전적인 영향을 미치고 고객 결제 계정에 요금이 청구됩니다. 자세한 내용은 API 결제 정보를 참고하세요.
  • Google Workspace 계정에는 모든 도메인을 포함할 수 있습니다. 다중 도메인 계정에서 한 도메인의 사용자는 다른 계정 도메인의 사용자와 서비스를 공유할 수 있습니다. 여러 도메인의 사용자에 관한 자세한 내용은 API 여러 도메인 정보를 참고하세요.
  • 중복 계정이 있을 수 있습니다. 추가하려는 사용자에게 이미 Google 계정이 있는지 확인합니다. 그런 다음 해당 계정과의 충돌을 방지하기 위한 단계를 따릅니다. 중복 계정 찾기 및 해결하기를 참고하세요.
  • 방문자 계정이 있을 수 있습니다. 사용자가 Drive에서 공동작업할 Google 계정이 없는 조직 외부의 사용자를 초대하면 방문자 계정(visitor's_username@your_domain.com 형식)이 생성됩니다. 방문자 계정과 동일한 사용자 이름을 가진 사용자를 추가하면 계정이 전체 Google Workspace 계정으로 전환됩니다. 계정에서 현재 Drive 파일 권한이 유지됩니다. 방문자와 문서 공유하기를 참고하세요.

응답이 성공하면 HTTP 200 상태 코드가 반환됩니다. 응답에는 상태 코드와 함께 새 사용자 계정의 속성이 반환됩니다.

사용자 계정 업데이트하기

사용자 계정을 업데이트하려면 다음 PUT 요청을 사용하고 승인 요청에 설명된 승인을 포함합니다. userKey는 사용자의 기본 이메일 주소, 고유한 사용자 id 또는 사용자의 별칭 이메일 주소 중 하나일 수 있습니다.

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey

요청 본문과 응답 본문 모두 User 인스턴스를 포함합니다. 하지만 Directory API는 패치 시맨틱을 지원하므로 요청에서 업데이트된 필드만 제출하면 됩니다.

샘플 요청

아래 예에서 사용자 계정이 생성될 때 사용자의 givenName은 '엘리자베스'였으며 직장 이메일 주소만 제공되었습니다.

{
  "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith"
   },
  "emails": [
    {
      "address": "[email protected]",
      "type": "work",
      "primary": true
    }
}

아래 요청은 givenName를 '엘리자베스'에서 '리즈'로 업데이트하고 집 이메일 주소도 추가합니다. 필드가 배열이므로 두 이메일 주소가 모두 완전히 제공됩니다.

PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]

{
  "name": {
    "givenName": "Liz",
   },
  "emails": [
    {
      "address": "[email protected]",
      "type": "work",
      "primary": true
    },
    {
      "address": "[email protected]",
      "type": "home"
    }
  ]
}

응답에 성공하면 HTTP 200 상태 코드와 업데이트된 필드가 포함된 User 리소스가 반환됩니다.

사용자의 계정 이름을 업데이트할 때는 다음 사항에 유의하세요.

  • 사용자 계정의 이름을 변경하면 사용자의 기본 이메일 주소와 이 사용자의 정보를 검색할 때 사용되는 도메인이 변경됩니다. 사용자 이름을 변경하기 전에 모든 브라우저 세션과 서비스에서 사용자를 로그아웃하는 것이 좋습니다.
  • 사용자 계정 이름을 변경하는 프로세스는 모든 서비스에 적용되기까지 최대 10분이 걸릴 수 있습니다.
  • 사용자 이름을 변경하면 이메일 전달 설정의 경우 메일이 계속 전송되도록 하기 위해 기존 사용자 이름이 별칭으로 유지되며 새 사용자 이름으로 사용할 수 없습니다.
  • 일반적으로 이메일 주소는 변경될 수 있으므로 사용자 이메일 주소를 영구 데이터의 키로 사용하지 않는 것이 좋습니다.
  • Google Workspace 앱에서 사용자 이름을 변경할 때의 영향을 모두 확인하려면 관리자 고객센터를 참고하세요.

사용자를 관리자로 지정하기

사용자를 최고 관리자로 만들려면 다음 POST 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. userKey는 사용자의 기본 이메일 주소, 순 사용자 id 또는 사용자의 별칭 이메일 주소 중 하나일 수 있습니다. 요청 및 응답 속성은 API 참조를 참고하세요. 최고 관리자에 대한 자세한 내용은 관리 고객센터를 참고하세요. 

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin

JSON 요청

이 예시에서 userKey가 [email protected]인 사용자가 최고 관리자가 되었습니다. 

POST https://admin.googleapis.com/admin/directory/v1/users/[email protected]/makeAdmin

{
 "status": true
}

응답이 성공하면 HTTP 200 상태 코드가 반환됩니다.

사용자 관계 관리

Directory API는 relations 필드를 사용하여 사용자 간의 다양한 유형의 관계를 정의합니다. 비즈니스 환경에서는 일반적으로 이 필드를 관리자-직원 및 조수 관계에 사용하지만, 이 필드는 다른 많은 유형도 지원합니다. 관계는 카드를 지원하는 모든 Google Workspace 애플리케이션의 사용자 '관련 사용자' 카드에 표시됩니다. 카드가 표시되는 위치의 예는 사용자의 디렉터리 프로필에 정보 추가하기를 참고하세요.

사용자 간의 관계 만들기

레코드에 relations 필드가 포함된 '소유' 사용자부터 시작하여 한 방향으로만 관계를 정의할 수 있습니다. type는 다른 사용자와 소유자 간의 관계를 설명합니다. 예를 들어 관리자-직원 관계에서 직원이 소유 사용자이고 manager 유형으로 relations 필드를 계정에 추가합니다. 허용되는 유형은 User 객체 참조를 참고하세요.

relations 필드가 포함된 JSON 요청 본문을 사용하여 소유자를 만들거나 업데이트하여 관계를 설정합니다. 하나의 요청으로 여러 관계를 만들 수 있습니다.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_1",
      "type": "manager"
    },
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "dotted_line_manager"
    }
  ]
}

관계 업데이트 또는 삭제하기

relations 필드는 전체적으로만 업데이트할 수 있습니다. 나열된 개별 사용자를 대상으로 관계 유형을 변경하거나 삭제할 수는 없습니다. 위 예에서 기존 관리자 관계를 삭제하고 점선 관리자를 소유자 사용자의 관리자로 만들려면 소유자 사용자의 계정을 원하는 모든 필드 값으로 업데이트합니다.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "manager"
    }
  ]
}

소유자 사용자의 모든 관계를 삭제하려면 relations를 비워둡니다.

{
  "relations": []
}

사용자 검색

사용자를 가져오려면 다음 GET 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. userKey는 사용자의 기본 이메일 주소, 순 사용자 id 또는 사용자의 별칭 이메일 주소 중 하나일 수 있습니다. 요청 및 응답 속성은 API 참조를 참고하세요. 

GET https://admin.googleapis.com/admin/directory/v1/users/userKey

이 예에서는 기본 또는 별칭 이메일 주소가 [email protected]인 사용자의 사용자 계정 속성을 반환합니다. 

GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]

JSON 응답

응답이 성공하면 HTTP 200 상태 코드가 반환됩니다. 응답에는 상태 코드와 함께 사용자 계정의 속성이 반환됩니다. 

{
 "kind": "directory#user",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "name": {
  "givenName": "Liz",
  "familyName": "Smith",
  "fullName": "Liz Smith"
 },
 "isAdmin": true,
 "isDelegatedAdmin": false,
 "lastLoginTime": "2013-02-05T10:30:03.325Z",
 "creationTime": "2010-04-05T17:30:04.325Z",
 "agreedToTerms": true,
 "hashFunction": "SHA-1",
 "suspended": false,
 "changePasswordAtNextLogin": false,
 "ipWhitelisted": false,
 "ims": [
  {
   "type": "work",
   "protocol": "gtalk",
   "im": "[email protected]",
   "primary": true
  }
 ],
 "emails": [
  {
   "address": "[email protected]",
   "type": "home",
   "customType": "",
   "primary": true
  }
 ],
 "addresses": [
  {
   "type": "work",
   "customType": "",
   "streetAddress": "1600 Amphitheatre Parkway",
   "locality": "Mountain View",
   "region": "CA",
   "postalCode": "94043"
  }
 ],
 "externalIds": [
  {
   "value": "employee number",
   "type": "custom",
   "customType": "office"
  }
 ],
 "organizations": [
  {
   "name": "Google Inc.",
   "title": "SWE",
   "primary": true,
   "customType": "",
   "description": "Software engineer"
  }
 ],
 "phones": [
  {
   "value": "+1 nnn nnn nnnn",
   "type": "work"
  }
 ],
 "aliases": [
  "[email protected]",
  "[email protected]"
 ],
 "nonEditableAliases": [
  "[email protected]"
 ],
 "customerId": "C03az79cb",
 "orgUnitPath": "corp/engineering",
 "isMailboxSetup": true,
 "includeInGlobalAddressList": true
}

도메인의 모든 사용자 가져오기

동일한 도메인의 모든 사용자를 가져오려면 다음 GET 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. 가독성을 위해 이 예시에서는 줄바꿈을 사용합니다. 

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=email, givenName, or familyName:the query's value*

요청 및 응답 속성은 API 참조를 참고하세요.

JSON 응답

이 예에서는 example.com 도메인의 모든 사용자가 응답 페이지당 최대 2개의 사용자 도메인과 함께 반환됩니다. 이 응답에는 후속 사용자 목록의 nextPageToken가 있습니다. 기본적으로 시스템은 사용자의 이메일 주소를 기준으로 알파벳순으로 100명의 사용자 목록을 반환합니다. 

GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2

응답이 성공하면 HTTP 200 상태 코드가 반환됩니다. 응답은 상태 코드와 함께 example.com 도메인의 사용자 계정 2개 (maxResults=2)를 반환합니다. 

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "[email protected]",
   "name": {
    "givenName": "Liz",
    "familyName": "Smith",
    "fullName": "Liz Smith"
   },
   "isAdmin": true,
   "isDelegatedAdmin": false,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "ims": [
    {
     "type": "work",
     "protocol": "gtalk",
     "im": "[email protected]",
     "primary": true
    }
   ],
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "addresses": [
    {
     "type": "work",
     "customType": "",
     "streetAddress": "1600 Amphitheatre Parkway",
     "locality": "Mountain View",
     "region": "CA",
     "postalCode": "94043"
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "organizations": [
    {
     "name": "Google Inc.",
     "title": "SWE",
     "primary": true,
     "customType": "",
     "description": "Software engineer"
    }
   ],
   "phones": [
    {
     "value": "+1 nnn nnn nnnn",
     "type": "work"
    }
   ],
   "aliases": [
    "[email protected]",
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "user unique ID",
   "primaryEmail": "[email protected]",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": true,
   "suspensionReason": "ADMIN",
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "contractor license number",
     "type": "custom",
     "customType": "work"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "next page token"
}

모든 계정 사용자 검색

여러 도메인으로 구성될 수 있는 계정의 모든 사용자를 가져오려면 다음 GET 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. 가독성을 위해 이 예시에서는 줄바꿈을 사용합니다. 

GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=user attributes
  • customer 쿼리 문자열은 my_customer 또는 customerId 값입니다.
  • my_customer 문자열을 사용하여 계정의 customerId를 나타냅니다.
  • 리셀러 관리자는 재판매된 고객의 customerId를 사용합니다. customerId의 경우 도메인의 모든 사용자 가져오기 작업 요청에서 계정의 기본 도메인 이름을 사용합니다. 결과 응답에는 customerId 값이 있습니다.
  • 선택사항인 orderBy 쿼리 문자열은 목록이 사용자의 기본 이메일 주소, 성 또는 이름순으로 정렬되는지 결정합니다. orderBy를 사용할 때 sortOrder 쿼리 문자열을 사용하여 결과를 오름차순 또는 내림차순으로 나열할 수도 있습니다.
  • 선택적 query 쿼리 문자열을 사용하면 핵심 필드와 맞춤 필드를 모두 포함하여 사용자 프로필의 여러 필드를 검색할 수 있습니다. 예시는 사용자 검색을 참고하세요.

요청 및 응답 속성은 API 참조를 참고하세요.

이 예에서는 계정 관리자가 각 응답 페이지에 하나의 사용자 항목과 함께 계정의 모든 사용자를 반환하도록 요청하고 있습니다. nextPageToken는 결과의 후속 페이지로 이동합니다. 

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1

이 예시에서 리셀러 관리자는 customerId 값이 C03az79cb인 재판매 계정의 모든 사용자를 요청하고 있습니다. 

GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1

JSON 응답

응답이 성공하면 HTTP 200 상태 코드가 반환됩니다. 응답에는 상태 코드와 함께 이 계정의 모든 사용자가 반환됩니다. 

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "[email protected]"
   ],
   "nonEditableAliases": [
     "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith",
    "fullName": "Elizabeth Smith"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": false,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "home",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "bank"
    }
   ],
   "relations": [
    {
     "value": "liz",
     "type": "friend",
     "customType": ""
    }
   ],
   "aliases": [
    "[email protected]",
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "name": {
    "givenName": "Tester",
    "familyName": "Three",
    "fullName": "Tester Three"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "name": {
    "givenName": "Admin",
    "familyName": "Work",
    "fullName": "Admin Work"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "NNNNN"
}

최근에 삭제된 사용자 검색

계정 또는 계정의 도메인 중 하나에서 지난 20일 동안 삭제된 모든 사용자를 검색하려면 다음 GET 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. 사용자 삭제를 취소하려면 사용자 삭제 취소하기를 참고하세요.

계정의 기본 도메인 또는 하위 도메인에서 지난 20일 동안 삭제된 사용자를 검색하려면 다음 GET 요청을 사용하세요. domain 쿼리 문자열은 도메인의 기본 도메인 이름입니다. 사용자 요청 및 응답 속성은 API 참조를 참고하세요. 가독성을 위해 이 예시에서는 줄바꿈을 사용합니다. 

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&showDeleted=true
 계정에 여러 도메인이 있는 경우 다음 GET 요청을 사용하여 전체 계정에서 지난 20일 동안 삭제된 사용자를 검색할 수 있습니다. 가독성을 위해 이 예시에서는 줄바꿈을 사용합니다. 
GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page&showDeleted=true
  • customer 쿼리 문자열은 my_customer 또는 customerId 값입니다.
  • 계정 관리자는 my_customer 문자열을 사용하여 계정의 customerId를 나타냅니다.
  • 리셀러 관리자는 재판매된 고객의 customerId를 사용합니다. customerId의 경우 도메인의 모든 사용자 가져오기 작업 요청에서 계정의 기본 도메인 이름을 사용합니다. 결과 응답에는 customerId 값이 있습니다.

요청 및 응답 속성은 API 참조를 참고하세요.

이 예에서는 계정 관리자가 계정에서 삭제된 모든 사용자를 요청하고 있습니다. 

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true

JSON 응답

응답이 성공하면 HTTP 200 상태 코드가 반환됩니다. 응답은 상태 코드와 함께 지난 20일 이내에 삭제된 모든 계정 사용자를 반환합니다. 

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "[email protected]"
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "[email protected]"
  }
 ],
 "nextPageToken": "token for next page of deleted users"
}

사용자 사진 검색

API는 최신 Google 프로필 사진인 사진 썸네일 1개를 가져옵니다. 사용자의 최신 사진을 가져오려면 다음 GET 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. userKey는 사용자의 기본 이메일 주소, 사용자 id 또는 사용자의 별칭 이메일 중 하나일 수 있습니다. 요청 및 응답 속성은 API 참조를 참고하세요. 

GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

이 예에서는 [email protected]의 최신 사진을 반환합니다.

GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail

JSON 응답

응답이 성공하면 HTTP 200 상태 코드가 반환됩니다. 

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

API의 웹 안전 base64 인코딩된 사진은 RFC 4648 'base64url'과 유사합니다. 이는 다음을 의미합니다.

  • 슬래시 (/) 문자가 밑줄 (_) 문자로 대체됩니다.
  • 플러스 기호 (+) 문자가 하이픈 (-) 문자로 대체됩니다.
  • 등호 (=) 문자가 별표 (*)로 대체됩니다.
  • 패딩의 경우 패딩에 등호(=)를 사용하는 RFC-4648 baseURL 정의 대신 마침표(.) 문자가 사용됩니다. 이는 URL 파싱을 단순화하기 위한 조치입니다.
  • 업로드되는 사진의 크기와 관계없이 API는 96x96픽셀로 비례하여 크기를 줄입니다.

JavaScript에서 호환되는 링크를 만들어야 하는 경우 Google Closure 라이브러리에 Apache 라이선스로 출시된 Base64 인코딩 및 디코딩 함수가 포함되어 있습니다.

관리자가 아닌 사용자로 사용자 검색

사용자 계정은 관리자만 수정할 수 있지만 도메인의 모든 사용자는 사용자 프로필을 읽을 수 있습니다. 비관리자는 viewType 매개변수가 domain_public인 users.get 또는 users.list 요청을 실행하여 사용자의 공개 프로필을 가져올 수 있습니다. 이 사용 사례에는 https://www.googleapis.com/auth/admin.directory.user.readonly 범위가 이상적입니다.

domain_public 뷰를 사용하면 관리자가 아닌 사용자가 표준 핵심 필드 세트에 액세스할 수 있습니다. 맞춤 필드의 경우 스키마를 정의할 때 공개 또는 비공개로 설정할지 선택할 수 있습니다.

사용자 사진 업데이트

사용자의 사진을 업데이트하려면 다음 PUT 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. userKey는 사용자의 기본 이메일 주소, 사용자 id 또는 사용자 별칭의 이메일 중 하나일 수 있습니다. 요청 및 응답 속성은 API 참조를 참고하세요. 

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

이 예에서는 [email protected]의 사진이 업데이트됩니다. 

PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail
 
{
"photoData": "web safe base64 encoded photo data"
}

사진을 업데이트할 때 API는 height 및 width를 무시합니다.

JSON 응답

응답이 성공하면 HTTP 200 상태 코드가 반환됩니다. 

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

사용자 사진 삭제하기

사용자의 사진을 삭제하려면 다음 DELETE 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. userKey는 사용자의 기본 이메일 주소, 사용자 id 또는 사용자 별칭의 이메일 중 하나일 수 있습니다. 요청 및 응답 속성은 API 참조를 참고하세요. 

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

삭제하면 사용자의 사진이 표시되지 않습니다. 사용자 사진이 필요한 모든 위치에 실루엣이 대신 표시됩니다.

사용자 계정 삭제

사용자 계정을 삭제하려면 다음 DELETE 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. userKey는 사용자의 기본 이메일 주소, 순 사용자 id 또는 사용자의 별칭 이메일 주소 중 하나일 수 있습니다. 요청 및 응답 속성은 API 참조를 참고하세요. 

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey

이 예에서는 [email protected] 사용자 계정이 삭제됩니다. 

DELETE https://admin.googleapis.com/admin/directory/v1/users/[email protected]

응답이 성공하면 HTTP 200 상태 코드만 반환됩니다.

사용자를 삭제하기 전에 고려해야 할 중요한 사항은 다음과 같습니다.

  • 삭제된 사용자는 더 이상 로그인할 수 없습니다.
  • 사용자 계정 삭제에 대한 자세한 내용은 관리 고객센터를 참고하세요.

사용자 계정 복구하기

지난 20일 이내에 삭제된 사용자는 특정 조건을 충족해야 계정을 복원할 수 있습니다.

사용자 계정의 삭제를 취소하려면 다음 POST 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. userKey는 지난 20일 이내에 삭제된 사용자 검색 작업의 응답에서 발견된 고유한 사용자 id입니다. 이 작업의 userKey에서는 사용자의 기본 이메일 주소 또는 사용자의 별칭 이메일 주소 중 하나를 사용할 수 없습니다. 요청 및 응답 속성은 API 참조를 참고하세요. 

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete

이 예에서는 [email protected] 사용자가 삭제 취소됩니다. 이 사용자의 이전 계정 속성이 모두 복원됩니다. 

POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete

응답이 성공하면 HTTP 204 상태 코드만 반환됩니다. 삭제되지 않은 사용자의 계정을 보려면 사용자 검색 작업을 사용하세요.