반응형
Implementing an HTTP Connection Server
이 문서는 Google Cloud Messaging(GCM) HTTP connnection server 를 기술합니다. Connection 서버들은 구글이 제공하는 서버들로서 애플리케이션 서버로부터 메시지를 받아서 단말기로 보냅니다.
Server Reference 를 보면 모든 메시지 파라메타들과 어떤 Connection 서버들을 지원하는지 볼 수 있습니다.
Authentication
메시지를 보내려면, 애플리케이션 서버는 하나의 POST 요청을 발행합니다. 예를 들면:
하나의 메시지 요청은 2개의 부분으로 만들어져 있습니다: HTTP 헤더와 HTTP 바디.
HTTP 헤더는 반드시 다음의 헤더들을 포함해야 합니다.:
- Authorization : key=YOUR_API_KEY
- Content-Type : applicaiton/json JSON 을 사용하기 위함; application/x-www-form-urlencoded;charset=UTF-8 plain text 를 사용하기 위함. 만약에 Content-Type 이 생략되었다면 메시지 형식이 plain text 라고 다정하게 될 것 입니다.
예를 들면:
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"data" : {
...
},
}
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"data" : {
...
},
}
HTTP 바디 내용은 여러분이 JSON을 사용했는지 plain text 를 사용했는지에 의존적 입니다. the Server Reference 를 보면 모든 JSON 파라메타들의 목록이나 plain text 메시지 가 포함할 수 있는 목록을 볼 수 있습니다.
Checking the validity of an API key
만약 메시지들을 보내고 인증 오류들을 받는다면, 여러분의 API 키에 대한 유효성을 검사해야 합니다. 예를 들면, 안드로이드에서, 다음의 명령어를 실행해 보세요.
# api_key=YOUR_API_KEY
# curl --header "Authorization: key=$api_key" \
--header Content-Type:"application/json" \
https://gcm-http.googleapis.com/gcm/send \
-d "{\"registration_ids\":[\"ABC\"]}"
만약 401 HTTP 상태 코드를 받는다면, 여러분의 API 키는 유효하지 않는 것입니다. 반면에 다음과 같은 것을 봐야만 하는데요.:
{"multicast_id":6782339717028231855,"success":0,"failure":1,
"canonical_ids":0,"results":[{"error":"InvalidRegistration"}]}
만약 여러분이 registration token 의 유효성을 확인받기를 원한다면, 여러분은 “ABC” 를 registration token 로 교체함으로써 수행할 수 있을 것 입니다.
Request Format
이 단락은 어떻게 요청들을 JSON 이나 plain text 형식으로 만드는지를 보여줍니다. 하나의 요청에 포함할 수 있는 필드(속성)들의 완벽한 목록은 Server Reference 를 보세요.
여기에 JSON 을 사용한 가장 작은 가능한 요청(어떤 파라메타도 없고 오직 받는사람만 있는 하나의 메시지)이 있습니다.
{ "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..." }
그리고 plain text 를 사용한 같은 예제가 있습니다.
registration_id=42
여기에 하나의 notification 메시지가 있습니다.
{ "notification": {
"title": "Portugal vs. Denmark","text": "5 to 1"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
notification 과 data 페이로드로 구성된 메시지들을 사용할 수 있는데요. notification 페이로드들에서 지원되는 키들에 대해서는 Server Referenece 를 보세요. notification 메시지와 메시지 옵션들에 대한 좀 더 많은 정보에 대해서는, Payload 를 보세요.
여기에 data 페이로드로 된 하나의 메시지가 있습니다.:
{ "data": {
"score": "5x1","time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
여기에는 모든 추가적인 필드(속성)들의 집합으로 된 하나의 메시지가 있습니다.
{ "collapse_key": "score_update",
"time_to_live": 108,"delay_while_idle": true,
"data": {
"score": "4x8",
"time": "15:16.2342"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
그리고 여기에는 plain-text 형식을 사용한 같은 메시지가 있습니다.:
collapse_key=score_update&time_to_live=108&delay_while_idle=1&data.score=4x8&data.time=15:16.2342®istration_id=42
만약 여러분의 조직에서 인터넷을 오고 가는 트래픽을 제한하는 방화벽을가지고 있다면, 여러분의 GCM 클라이언트 앱들이 메시지를 받기 위해서 GCM 과의 연결성을 허락하기 위한 설정이 필요합니다. 열어야 하는 포트들이 있는데요: 5228, 5229 그리고 5230 입니다. GCM 은 전형적으로 오직 5228을 사용하는데, 하지만 때때로 5229 와 5230 을 사용하기도 합니다. GCM 은 특정한 IP들만 제공하지 않는데, 그래서 여러분의 방화벽이 외부로 나가는 모든 IP 주소들에 대한 연결들(15169 개의 구글의 ASN 안의 IP 블락 목록들에 포함된)에 대해 받아들일 수 있도록 허락해야만 합니다.
Response format
메시지를 보내려고 시도했을 때 두 가지 가능한 결과가 있습니다.:
- 메시지는 성공적으로 처리되었다. HTTP 응답은 200 상태를 가지게 되고, 바디는 메시지의 상태에 대한 더 많은 정보를 가지게 됩니다.
- GCM 은 요청을 거부한다. HTTP 응답은 200이 아닌 상태 코드를 지니게 됩니다(400, 401 또는 5xx 같은).
하나의 JSON 요청이 성공적일 때(HTTP 상태 코드가 200), JSON 객체가 Downstream HTTP message response body를 담은 채로 반환됩니다. 모든 메시지들에 대한 메시지 ID 값을 로그로 남기는데, 이 경우에 여러분은 구글의 지원이나 GCM diagnotics 를 통해서 메 시지의 문제를 해결해할 필요가 있게 됩니다.
만약 failure의 값과 canonical_ids이 0이면, 응답의 나머지를 분석할 필요가 없게 됩니다. 반면에, 우리가 추천하는 것은 여러분이 결과 필드(속성)를 통해서 반복하고 다음 목록의 각 객체에 대해 아래에 있는 것을 실해하는 것 입니다:
- 만약 message_id가 설정되어 있으면, registration_id를 검사하세요.:
- 만약 registration_id가 설정되면, 여러분의 서버 데이터베이스에서 original ID 를 새로운 값(canonical ID)으로 바꿔줘야 합니다. 알아두어야 할 것이 있는데 original ID 는 결과의 부분이 아닌데, 그래서 여러분은 요청으로 전달된 registration_ids의 목록으로부터 그것을 획득할 필요가 있습니다(같은 인덱스를 사용하는).
- 그 외에는, error 값을 가지게 됩니다.
- 만약 에러가 Unavailable 라면, 여러분은 다른 요청으로 메시지를 보내는 것을 다시 시도 할 수 있습니다.
- 만약 에러가 NotRegistered 라면, 여러분은 서버 데이터베이스로부터 registration ID 를 지워야만하는데 왜냐하면 애플리케이션이 단말기에 설치되지 않았기 때문이거나, 클라이언트 앱이 메시지를 받도록 설정되지 않았기 때문입니다.
- 그 외에는, 요청으로 전달된 registration token 에 어떤 문제가 있습니다; 그것은 아마도 회복불가능한 에러일텐데 서버 데이터베이스로부터 그 등록을 제거하기를 요구할 것 입니다. 모든 가능한 에러 값들에 대해서는 Downstream message error reponse codes 를 보세요.
하나의 plain-text 요청이 성공적일 경우에(HTTP 상태 코드가 200), 응답 바디는 key/value 쌍의 형식으로 1 또는 2 줄을 가지고 있습니다. 첫 번째 줄은 항상 이용가능하고 그 내용은 id=ID of sent message 이거나 Error=GCM error code 입니다. 두 번째 줄은, 만악에 이용할 수 있다면, registration_id=canonical ID 의 형식을 가지게 됩니다. 두 번째 줄은 추가적인 것이며, 그리고 첫 번째 줄이 에러가 아닐 때 보내질 수 있습니다. 우리는 JSON 응답을 처리하는 것과 같은 방법으로 plain-text 응답을 처리하는 것을 추천합니다.:
만약 첫 번째 줄이 id 로 시작한다면, 두 번째 줄을 검사하세요:
만약에 두 번째 줄이 registration_id로 시작한다면, 값을 얻을 수 있고 여러분의 서버 데이터베이스의 registration token 을 교체 할 수 있습니다.
그 외에는, Error 값을 받습니다.:
만약 에러 값이 NotRegistered 라면, 여러분의 서버 데이터베이스에서 registration token 을 제거하세요.
그 외에는, 복구할 수 없는 에러들이 있습니다(알아두어야 할 것: Plain-text 요청들은 에러 코드에 대해서 결코 Unavailable를 반환하지 않을 것 이고, 대신에 500 HTTP 상태를 반환하게 될 것 입니다).
이 단락은 성공적으로 처리된 메시지들을 나타내는 응답들의 몇 가지 예제들을 보여줍니다. 응답들이 기반이 되는 요청들에 대한 Request Format 을 보세요.
여기는 응답으로 한 받는 사람에게 canonical IDs 없이 성공적으로 보내진 JSON 메시지 의 간단한 경우 입니다.
{ "multicast_id": 108,
"success": 1,"failure": 0,
"canonical_ids": 0,
"results": [
{ "message_id": "1:08" }
]
}
또는 만약 요청이 plain-text 형식인 경우:
id=1:08
아래에는 3개의 성공적으로 처리된 메시지와 함께 6의 수신자(각각 IDs 4, 8, 15, 16, 23 그리고 42)에 대한 JSON 결과들인데, 1 개의 canonical registration token 이 반환되었으며, 그리고 3개의 에러가 있습니다:
{ "multicast_id": 216,
"success": 3,"failure": 3,
"canonical_ids": 1,
"results": [
{ "message_id": "1:0408" },
{ "error": "Unavailable" },
{ "error": "InvalidRegistration" },
{ "message_id": "1:1516" },
{ "message_id": "1:2342", "registration_id": "32" },
{ "error": "NotRegistered"}
]
}
이 예제 안에서:
- 첫 번째 메시지 : 성공, not required.
- 두 번째 메시지 : 재전송 되어야만 함(to registration token 8).
- 세 번째 메시지 : 복구할 수 없는 에러(그 값은 데이터베이스에서 오류를 일으키게 될 것 입니다).
- 네 번째 메시지 : 성공, nothing required.
- 다섯 번째 메시지 : 성공, 그러나 registration token 이 서버 데이터베이스에서 갱신되어야만 합니다(from 23 to 32).
- 여섯 번째 메시지 : registration token(42) 는 서버 데이터베이스에서 삭제되어야만 하는데 왜냐하면 애플리케이션이 단말기에서 삭제되었기 때문입니다.
또는 단지 위의 세 번째 메시지가 plain-text 형식을 사용해서 보내졌다면:
Error=InvalidRegistration
만약 위의 다섯 번째 메시지가 plain-text 형식을 사용해서 보내졌다면:
id=1:2342
registration_id=32
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
반응형