푸시 알림

개요

Gmail API는 Gmail 편지함의 변경사항을 감시할 수 있는 서버 푸시 알림을 제공합니다. 이 기능을 사용하여 애플리케이션 성능을 개선할 수 있습니다. 리소스 폴링과 관련된 추가 네트워크 및 컴퓨팅 비용을 없애 리소스 변경 여부를 확인할 수 있습니다. 편지함이 변경될 때마다 Gmail API가 백엔드 서버 애플리케이션에 알립니다.

초기 Cloud Pub/Sub 설정

Gmail API는 Cloud Pub/Sub API를 사용하여 푸시 알림을 전송합니다. 이렇게 하면 단일 정기 결제 엔드포인트에서 웹훅과 폴링을 비롯한 다양한 방법을 통해 알림을 받을 수 있습니다.

기본 요건

이 설정의 나머지 부분을 완료하려면 Cloud Pub/Sub 기본 요건을 충족한 후 Cloud Pub/Sub 클라이언트를 설정해야 합니다.

주제 만들기

Cloud Pub/Sub 클라이언트를 사용하여 Gmail API가 알림을 보낼 주제를 만듭니다. 주제 이름은 프로젝트에서 선택할 수 있는 모든 이름일 수 있습니다.즉, 일치하는 projects/myproject/topics/*입니다. 여기서 myproject는 Google Developers Console에서 프로젝트의 프로젝트 ID입니다.

주제 수의 Cloud Pub/Sub 제한으로 인해 애플리케이션의 모든 Gmail API 푸시 알림에 단일 주제를 사용하는 것이 좋습니다.

구독 만들기

Cloud Pub/Sub 구독자 가이드를 따라 내가 만든 주제에 대한 구독을 설정합니다. 정기 결제 유형을 웹훅 푸시 (예: HTTP POST 콜백) 또는 풀 (앱에서 시작됨)으로 구성합니다. 이 방법으로 애플리케이션에서 업데이트 알림을 받게 됩니다.

주제에 게시 권한 부여

Cloud Pub/Sub를 사용하려면 주제에 알림을 게시할 권한을 Gmail에 부여해야 합니다.

이렇게 하려면 gmail-api-push@system.gserviceaccount.com에 publish 권한을 부여해야 합니다. 리소스 수준 액세스 제어 안내에 따라 Cloud Pub/Sub 개발자 콘솔 권한 인터페이스를 사용하여 이 작업을 수행할 수 있습니다.

Gmail 편지함 업데이트 받기

초기 Cloud Pub/Sub 설정이 완료되면 편지함 업데이트에 대한 알림을 보내도록 Gmail 계정을 구성합니다.

시청 요청

Cloud Pub/Sub 주제로 알림을 보내도록 Gmail 계정을 구성하려면 다른 Gmail API 호출과 마찬가지로 Gmail API 클라이언트를 사용하여 Gmail 사용자 편지함에서 watch를 호출하기만 하면 됩니다. 이렇게 하려면 위에서 만든 주제 이름과 필터링할 labels와 같은 watch 요청의 다른 옵션을 제공합니다. 예를 들어 받은편지함이 변경될 때마다 알림을 받으려면 다음 단계를 따르세요.

프로토콜

POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json

{
  topicName: "projects/myproject/topics/mytopic",
  labelIds: ["INBOX"],
  labelFilterBehavior: "INCLUDE",
}

Python

request = {
  'labelIds': ['INBOX'],
  'topicName': 'projects/myproject/topics/mytopic',
  'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()

대답 보기

watch 요청이 성공하면 다음과 같은 응답이 수신됩니다.

{
  historyId: 1234567890
  expiration: 1431990098200
}

사용자의 현재 편지함(historyId)으로 변경합니다. 그 이후의 모든 변경사항은 historyId에 알림이 전송됩니다. 이 historyId 이전에 변경사항을 처리해야 하는 경우 동기화 가이드를 참고하세요.

또한 watch 호출이 성공하면 알림이 Cloud Pub/Sub 주제로 즉시 전송됩니다.

watch 호출에서 오류가 발생하면 세부정보가 문제의 원인을 설명해야 합니다. 문제의 원인은 일반적으로 Cloud Pub/Sub 주제 및 구독 설정과 관련이 있습니다. Cloud Pub/Sub 문서를 참조하여 설정이 올바른지 확인하고 주제 및 구독 문제 디버깅에 도움을 받으세요.

편지함 워치 갱신 중

적어도 7일마다 watch를 다시 호출해야 합니다. 그러지 않으면 사용자에 관한 업데이트 수신이 중지됩니다. 하루에 한 번 watch를 호출하는 것이 좋습니다. watch 응답에는 watch 만료에 대한 타임스탬프가 있는 만료 필드도 있습니다.

알림 수신

watch와 일치하는 편지함 업데이트가 발생할 때마다 애플리케이션이 변경사항을 설명하는 알림 메시지를 수신합니다.

푸시 정기 결제를 구성한 경우 서버의 웹훅 알림은 PubsubMessage을 따릅니다.

POST https://yourserver.example.com/yourUrl
Content-type: application/json

{
  message:
  {
    // This is the actual notification data, as base64url-encoded JSON.
    data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",

    // This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
    "messageId": "2070443601311540",

    // This is the publish time of the message.
    "publishTime": "2021-02-26T19:13:55.749Z",
  }

  subscription: "projects/myproject/subscriptions/mysubscription"
}

HTTP POST 본문은 JSON이고 실제 Gmail 알림 페이로드는 message.data 필드에 있습니다. 이 message.data 필드는 사용자의 이메일 주소와 새 편지함 기록 ID가 포함된 JSON 객체로 디코딩되는 base64url로 인코딩된 문자열입니다.

{"emailAddress": "user@example.com", "historyId": "9876543210"}

그런 다음 history.list를 사용하여 동기화 가이드에 따라 마지막으로 알려진 historyId 이후 사용자의 변경사항 세부정보를 가져올 수 있습니다.

대신 가져오기 구독을 구성한 경우 메시지 수신에 대한 자세한 내용은 Cloud Pub/Sub 구독자 가져오기 가이드의 코드 샘플을 참조하세요.

알림에 응답하기

모든 알림을 확인해야 합니다. 웹훅 푸시 전송을 사용하는 경우 성공적으로 응답 (예: HTTP 200)하면 알림이 확인됩니다.

가져오기 전송(REST Pull, RPC Pull 또는 RPC StreamingPull)을 사용할 경우 확인 호출(REST 또는 RPC)으로 후속 조치를 취해야 합니다. 공식 RPC 기반 클라이언트 라이브러리를 사용하여 비동기식 또는 동기식으로 메시지를 확인하는 방법에 대한 자세한 내용은 Cloud Pub/Sub 구독자 가져오기 가이드의 코드 샘플을 참조하세요.

알림이 확인되지 않으면 (예: 웹훅 콜백이 오류를 반환하거나 시간 초과) Cloud Pub/Sub는 나중에 알림을 다시 시도합니다.

편지함 업데이트 중지

편지함에서 업데이트 수신을 중지하려면 stop를 호출합니다. 그러면 모든 새 알림이 몇 분 내에 중지되어야 합니다.

제한사항

최대 알림 비율

감시 중인 각 Gmail 사용자의 최대 알림 빈도는 이벤트 1회입니다. 이보다 많은 사용자 알림은 삭제됩니다. 알림을 처리할 때 다른 알림을 트리거하여 알림 루프가 시작되지 않도록 주의하세요.

안정성

일반적으로 모든 알림은 몇 초 내에 안정적으로 전송되지만, 일부 극단적인 상황에서는 알림이 지연되거나 삭제될 수 있습니다. 푸시 메시지가 수신되지 않더라도 애플리케이션이 계속 동기화되도록 이 가능성을 적절하게 처리해야 합니다. 예를 들어 사용자에게 알림이 없는 기간이 지나면 주기적으로 history.list를 호출하는 방식으로 대체합니다.

Cloud Pub/Sub 제한사항

Cloud Pub/Sub API에는 자체 제한사항도 있습니다. 특히 pricing 및 quotas 문서에 자세히 설명되어 있습니다.