개요
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에 부여해야 합니다.
이렇게 하려면 publish 권한을 gmail-api-push@system.gserviceaccount.com에 부여해야 합니다. 이를 수행하려면 리소스 수준 액세스 제어 안내에 따라 Cloud Pub/Sub 개발자 콘솔 권한 인터페이스를 사용하면 됩니다.
Gmail 편지함 업데이트 받기
초기 Cloud Pub/Sub 설정이 완료되면 편지함 업데이트에 대한 알림을 보내도록 Gmail 계정을 구성합니다.
시계 요청
Cloud Pub/Sub 주제에 알림을 보내도록 Gmail 계정을 구성하려면 다른 Gmail API 호출과 마찬가지로 Gmail API 클라이언트를 사용하여 Gmail 사용자 편지함에서 watch()를 호출하기만 하면 됩니다.
이렇게 하려면 위에서 만든 주제 이름과 watch() 요청의 다른 옵션(예: 필터링할 labels)을 제공합니다. 예를 들어 받은편지함이 변경될 때마다 알림을 받으려면 다음 단계를 따르세요.
프로토콜
POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json
{
topicName: "projects/myproject/topics/mytopic",
labelIds: ["INBOX"],
}
Python
request = {
'labelIds': ['INBOX'],
'topicName': 'projects/myproject/topics/mytopic'
}
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) 알림을 확인합니다.
pull 전송(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에도 자체 제한사항이 있으며, 자세한 내용은 가격 책정 및 할당량 문서를 참조하세요.