이 문서에서는 Gmail API에서 푸시 알림을 관리하는 방법을 설명합니다.
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 Cloud 콘솔에 프로젝트에 대해 나열된 프로젝트 ID임).
구독 만들기
만든 주제에 대한 구독을 설정하려면 Cloud Pub/Sub 구독 유형 가이드를 따르세요. 구독 유형을 웹훅 푸시 (즉, HTTP POST 콜백) 또는 풀 (즉, 앱에서 시작됨)로 구성합니다. 애플리케이션이 업데이트 알림을 수신하는 방법입니다.
주제에 게시 권한 부여
Cloud Pub/Sub를 사용하려면 주제에 알림을 게시할 권한을 Gmail에 부여해야 합니다.
이렇게 하려면 gmail-api-push@system.gserviceaccount.com에 publish 권한을 부여합니다. Google Cloud 콘솔의 Cloud Pub/Sub 권한 콘솔을 사용하여 이 작업을 수행할 수 있습니다. 액세스 제어 안내를 따르세요.
조직의 도메인 제한 공유 구성으로 인해 게시 권한을 부여하지 못할 수 있습니다. 이 문제를 해결하려면 이 서비스 계정에 대해 예외를 구성하면 됩니다.
Gmail 메일함 업데이트 받기
초기 Cloud Pub/Sub 설정이 완료되면 사서함 업데이트 알림을 전송하도록 Gmail 계정을 구성합니다.
시청 요청
Gmail 계정이 Cloud Pub/Sub 주제로 알림을 보내도록 구성하려면 Gmail API 클라이언트를 사용하여 Gmail 사용자 편지함에서 watch 메서드를 호출하세요. 이는 다른 Gmail API 호출과 유사합니다. 만든 주제 이름과 필터링할 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 전에 변경사항을 처리해야 하는 경우 Gmail API로 클라이언트 동기화를 참고하세요.
또한 watch 호출이 성공하면 알림이 Cloud Pub/Sub 주제로 즉시 전송됩니다.
watch 호출에서 오류가 발생하면 세부정보에 문제의 소스가 설명되어야 합니다. 일반적으로 Cloud Pub/Sub 주제 및 구독 설정에 문제가 있습니다. Cloud Pub/Sub 문서를 참고하여 설정이 올바른지 확인하고 주제 및 구독 문제를 디버깅하세요.
편지함 감시 갱신
7일마다 한 번 이상 watch를 호출해야 합니다. 그렇지 않으면 사용자 업데이트를 수신할 수 없습니다. 하루에 한 번 watch을 호출하는 것이 좋습니다. watch 메서드 응답에는 watch 만료 타임스탬프가 있는 expiration 필드도 있습니다.
알림 수신
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 필드는 Base64URL로 인코딩된 문자열로, 이 문자열은 사용자의 이메일 주소와 새 메일함 기록 ID가 포함된 JSON 객체로 디코딩됩니다.
{"emailAddress": "user@example.com", "historyId": "9876543210"}
그런 다음 Gmail API로 클라이언트 동기화에 설명된 대로 history.list 메서드를 사용하여 마지막으로 알려진
historyId 이후 사용자의 변경사항 세부정보를 가져올 수 있습니다.
예를 들어 history.list 메서드를 사용하여 초기 watch 요청과 이전 예에 공유된 알림 메시지 수신 사이에 발생한 변경사항을 식별합니다. 1234567890를 history.list에 startHistoryId로 전달합니다. 그런 다음 나중에 사용할 수 있도록 9876543210를 마지막으로 알려진 historyId로 유지할 수 있습니다.
풀 구독을 구성한 경우 메시지 수신에 관한 자세한 내용은 Cloud Pub/Sub의 풀 구독 가이드에 있는 코드 샘플을 참고하세요.
알림에 대한 응답
모든 알림을 확인해야 합니다. 웹훅 푸시 전송을 사용하는 경우 성공적으로 응답 (예: HTTP 200)하면 알림이 확인됩니다.
풀 전송 (REST 풀, RPC 풀 또는 RPC StreamingPull)을 사용하는 경우 승인 호출(REST 또는 RPC)을 후속 조치로 실행해야 합니다. 공식 RPC 기반 클라이언트 라이브러리를 사용하여 비동기식 또는 동기식으로 메시지를 승인하는 방법에 관한 자세한 내용은 Cloud Pub/Sub의 풀 구독 가이드에 있는 코드 샘플을 참고하세요.
알림을 확인하지 않으면 (예: 웹훅 콜백이 오류를 반환하거나 시간이 초과되는 경우) Cloud Pub/Sub가 나중에 알림을 다시 시도합니다.
편지함 업데이트 중지
메일함의 업데이트 수신을 중지하려면 stop 메서드를 호출합니다. 몇 분 이내에 모든 새 알림이 중지됩니다.
제한사항
다음은 서버 푸시 알림 사용 시의 제한사항입니다.
최대 알림 비율
모니터링되는 각 Gmail 사용자의 최대 알림 비율은 초당 이벤트 1개입니다. 이 비율을 초과하는 사용자 알림은 삭제됩니다. 알림을 처리할 때는 알림 루프를 시작할 수 있는 다른 알림을 트리거하지 않도록 주의하세요.
안정성
일반적으로 모든 알림은 몇 초 이내에 안정적으로 전송되지만, 극단적인 상황에서는 알림이 지연되거나 삭제될 수 있습니다.
푸시 메시지가 수신되지 않더라도 애플리케이션이 계속 동기화되도록 이 가능성을 적절하게 처리하세요. 예를 들어 사용자에게 알림이 없는 기간이 지난 후 주기적으로 history.list 메서드를 호출하도록 대체합니다.
Cloud Pub/Sub 제한사항
Cloud Pub/Sub API에도 자체 제한사항이 있으며, 이는 가격 및 할당량 문서에 자세히 설명되어 있습니다.