REST Resource: subscriptions

리소스: 구독

Google Workspace 리소스에 관한 이벤트를 수신하는 구독입니다. 구독에 대해 자세히 알아보려면 Google Workspace Events API 개요를 참고하세요.

JSON 표현 
{
  "name": string,
  "uid": string,
  "targetResource": string,
  "eventTypes": [
    string
  ],
  "payloadOptions": {
    object (PayloadOptions)
  },
  "notificationEndpoint": {
    object (NotificationEndpoint)
  },
  "state": enum (State),
  "suspensionReason": enum (ErrorType),
  "authority": string,
  "createTime": string,
  "updateTime": string,
  "reconciling": boolean,
  "etag": string,

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
필드
name

string

식별자. 정기 결제의 리소스 이름입니다.

형식: subscriptions/{subscription}
uid

string

출력 전용입니다. 구독에 대해 시스템에서 할당된 고유 식별자입니다.
targetResource

string

필수 항목입니다. 변경할 수 없습니다. 이벤트에 대해 모니터링되는 Google Workspace 리소스이며 전체 리소스 이름 형식입니다. 타겟 리소스와 타겟 리소스에서 지원하는 이벤트에 대해 알아보려면 지원되는 Google Workspace 이벤트를 참고하세요.

사용자는 앱이 주어진 대상 리소스에 하나의 구독을 만들도록 승인만 할 수 있습니다. 앱이 동일한 사용자 인증 정보로 다른 정기 결제를 만들려고 하면 요청에서 ALREADY_EXISTS 오류를 반환합니다.
eventTypes[]

string

필수 항목입니다. 순서가 지정되지 않은 목록입니다. 정기 결제 생성을 위한 입력입니다. 그렇지 않으면 출력 전용입니다. 타겟 리소스에 관해 수신할 이벤트 유형 1개 이상 CloudEvents 사양에 따라 형식이 지정됩니다.

지원되는 이벤트 유형은 구독의 대상 리소스에 따라 다릅니다. 자세한 내용은 지원되는 Google Workspace 이벤트를 참고하세요.

기본적으로 정기 결제의 수명 주기에 관한 이벤트도 수신됩니다. 이 필드의 수명 주기 이벤트는 지정할 필요가 없습니다.

타겟 리소스에 존재하지 않는 이벤트 유형을 지정하면 요청에서 HTTP 400 Bad Request 상태 코드를 반환합니다.
payloadOptions

object (PayloadOptions)

선택사항입니다. 이벤트 페이로드에 포함할 데이터에 관한 옵션입니다. Google Chat 이벤트에만 지원됩니다.
notificationEndpoint

object (NotificationEndpoint)

필수 항목입니다. 변경할 수 없습니다. 구독이 이벤트를 전송하는 엔드포인트(예: Pub/Sub 주제)입니다.
state

enum (State)

출력 전용입니다. 정기 결제의 상태입니다. 구독이 이벤트를 수신하고 알림 엔드포인트로 전송할 수 있는지 확인합니다.
suspensionReason

enum (ErrorType)

출력 전용입니다. 구독이 정지된 오류입니다.

정기 결제를 다시 활성화하려면 오류를 해결하고 subscriptions.reactivate 메서드를 호출합니다.
authority

string

출력 전용입니다. 정기 결제 생성을 승인한 사용자입니다.

형식: users/{user}

Google Workspace 사용자의 경우 {user} 값은 Directory API의 user.id 필드입니다.
createTime

string (Timestamp format)

출력 전용입니다. 구독이 생성된 시간입니다.
updateTime

string (Timestamp format)

출력 전용입니다. 구독이 마지막으로 업데이트된 시간입니다.
reconciling

boolean

출력 전용입니다. true인 경우 정기 결제가 업데이트되는 중입니다.
etag

string

선택사항입니다. 이 체크섬은 다른 필드의 값을 기준으로 서버에서 계산되며, 처리 전 클라이언트에 최신 값이 적용되도록 업데이트 요청이 있을 때 전송될 수 있습니다.

통합 필드 expiration. 구독이 만료되는 시간입니다.

최대 만료 시간은 구독에 이벤트 페이로드(PayloadOptions 필드에 지정됨)에 리소스 데이터가 포함되어 있는지에 따라 다릅니다.

  • 페이로드에서 리소스 데이터를 생략하는 경우 최대 7일
  • 페이로드에 리소스 데이터가 포함된 경우 최대 4시간 Google Workspace 조직에서 도메인 전체 위임을 통해 리소스에 대한 액세스 권한을 부여하는 경우 구독 만료 시간을 최대 24시간까지 연장할 수 있습니다.

정기 결제가 만료되면 자동으로 삭제됩니다. 정기 결제가 만료되기 12시간 전과 1시간 전에 notification_endpoint에 수명 주기 이벤트가 수신됩니다. 자세한 내용은 수명 주기 이벤트 수신 및 응답을 참고하세요.

정기 결제가 만료되지 않도록 하려면 UpdateSubscription 메서드를 사용하여 만료일을 연장하면 됩니다. 자세한 내용은 구독 업데이트 또는 갱신하기를 참고하세요. expiration은 다음 중 하나일 수 있습니다.
expireTime

string (Timestamp format)

비어 있지 않은 기본값 구독이 만료되는 시간의 타임스탬프(UTC 기준)입니다. 입력에 사용된 것과 관계없이 항상 출력에 표시됩니다.
ttl

string (Duration format)

입력 전용입니다. 구독의 TTL(수명) 또는 기간입니다. 지정하지 않거나 0로 설정하면 가능한 최대 기간을 사용합니다.

PayloadOptions

이벤트 페이로드에 포함할 데이터에 관한 옵션입니다. Google Chat 이벤트에만 지원됩니다.

JSON 표현 
{
  "includeResource": boolean,
  "fieldMask": string
}
필드
includeResource

boolean

선택사항입니다. 이벤트 페이로드에 변경된 리소스에 관한 데이터가 포함되는지 여부입니다. 예를 들어 Google Chat 메시지가 생성된 이벤트의 경우 페이로드에 Message 리소스에 대한 데이터가 포함되어 있는지 확인합니다. false인 경우 이벤트 페이로드에는 변경된 리소스의 이름만 포함됩니다.
fieldMask

string (FieldMask format)

선택사항입니다. includeResource가 true로 설정된 경우 이벤트 페이로드에 포함할 필드 목록입니다. 필드는 쉼표로 구분합니다. 예를 들어 Google Chat 메시지 발신자를 포함하고 시간을 만들려면 message.sender,message.createTime을 입력합니다. 생략하면 페이로드에 리소스의 모든 필드가 포함됩니다.

리소스에 존재하지 않는 필드를 지정하면 시스템에서 필드를 무시합니다.

NotificationEndpoint

구독이 이벤트를 전달하는 엔드포인트입니다.

JSON 표현 
{

  // Union field endpoint can be only one of the following:
  "pubsubTopic": string
  // End of list of possible types for union field endpoint.
}
필드

통합 필드 endpoint.

endpoint는 다음 중 하나여야 합니다.
pubsubTopic

string

변경할 수 없습니다. 구독에 대한 이벤트를 수신하는 Cloud Pub/Sub 주제입니다.

형식: projects/{project}/topics/{topic}

이 구독을 만드는 Google Cloud 프로젝트와 동일한 프로젝트에서 주제를 만들어야 합니다.

주제가 이벤트를 수신하면 이벤트가 Cloud Pub/Sub 메시지로 인코딩됩니다. 자세한 내용은 CloudEvents용 Google Cloud Pub/Sub 프로토콜 바인딩을 참고하세요.

주

정기 결제의 가능한 상태입니다.

열거형
STATE_UNSPECIFIED 기본값 이 값은 사용되지 않습니다.
ACTIVE 구독이 활성 상태이며 이벤트를 수신하고 알림 엔드포인트로 전송할 수 있습니다.
SUSPENDED 오류로 인해 구독에서 이벤트를 수신할 수 없습니다. 오류를 식별하려면 suspensionReason 필드를 참조하세요.
DELETED 구독이 삭제됩니다.

ErrorType

정기 결제에 발생할 수 있는 오류입니다.

열거형
ERROR_TYPE_UNSPECIFIED 기본값 이 값은 사용되지 않습니다.
USER_SCOPE_REVOKED 승인 사용자가 하나 이상의 OAuth 범위 부여를 취소했습니다. Google Workspace 승인에 대해 자세히 알아보려면 OAuth 동의 화면 구성을 참고하세요.
RESOURCE_DELETED 구독의 대상 리소스가 더 이상 존재하지 않습니다.
USER_AUTHORIZATION_FAILURE 정기 결제 생성을 승인한 사용자는 더 이상 정기 결제의 대상 리소스에 액세스할 수 없습니다.
ENDPOINT_PERMISSION_DENIED Google Workspace 애플리케이션은 구독의 알림 엔드포인트에 이벤트를 전송할 수 없습니다.
ENDPOINT_NOT_FOUND 구독의 알림 엔드포인트가 존재하지 않거나 구독을 만든 Google Cloud 프로젝트에서 엔드포인트를 찾을 수 없습니다.
ENDPOINT_RESOURCE_EXHAUSTED 할당량이 부족하거나 비율 제한에 도달하여 구독의 알림 엔드포인트가 이벤트를 수신하지 못했습니다.
OTHER 알 수 없는 오류가 발생했습니다.

메서드

create

 Google Workspace 구독을 만듭니다.

delete

 Google Workspace 구독을 삭제합니다.

get

 Google Workspace 구독에 관한 세부정보를 가져옵니다.

list

 Google Workspace 구독을 표시합니다.

patch

 Google Workspace 구독을 업데이트하거나 갱신합니다.

reactivate

 정지된 Google Workspace 구독을 재활성화합니다.