gcp-pubsub-pull
구글 클라우드 Pub/Sub 구독의 메시지를 소비하지 않고 조회합니다. 조회한 메시지는 구독에 그대로 남으므로, 같은 구독을 사용하는 수집기가 해당 메시지를 정상적으로 수집합니다.
- profile=PROFILE
- 구글 클라우드 Pub/Sub 접속 프로파일 식별자. 미지정 시 등록된 프로파일이 하나뿐이면 그것을 사용하고, 둘 이상이면 오류가 발생합니다.
- subscription-id=SUBSCRIPTION-ID
- 구글 클라우드 Pub/Sub의 구독 ID. 주제 ID가 아닙니다.
- limit=INT
- 조회할 최대 메시지 건수. 1에서 1000 사이로 지정하며 미지정 시 10입니다. Pub/Sub 특성상 지정한 건수보다 적게 반환될 수 있습니다.
- timeout=INT
- 빈 구독에서 메시지를 기다리는 최대 시간. 초 단위로 2에서 20 사이로 지정하며 미지정 시 2입니다. 값이 작으면 네트워크 지연이나 서버 응답 시간에 따라 구독에 메시지가 있어도 결과가 나오지 않을 수 있습니다.
출력 필드
| 필드 | 타입 | 이름 | 설명 |
|---|---|---|---|
| _time | 날짜 | 시각 | 메시지가 게시된 시각 |
| profile | 문자열 | 프로파일 | 구글 클라우드 Pub/Sub 접속 프로파일 식별자 |
| subscription_id | 문자열 | 구독 ID | 조회한 구독 ID |
| msg_id | 문자열 | 메시지 ID | 주제 내에서 유일한 메시지 ID |
| msg | 문자열 | 메시지 | UTF-8 해석된 메시지 문자열 |
| attrs | 맵 | 속성 | 메시지 속성 키-값 목록 |
필요한 권한은 Pub/Sub 구독자(roles/pubsub.subscriber)이며, Pub/Sub 뷰어로는 메시지를 가져올 수 없습니다. 액세스 제어 문서를 참고하십시오.
동작 방식
단항 Pull(unary pull)로 메시지를 한 번 읽습니다. 수집기와 달리 연결을 유지하지 않습니다.
읽은 메시지는 확인 응답하지 않고, 구독으로 즉시 돌려줍니다. 돌려주는 요청이 실패해도 구독의 확인 기한이 지나면 자동으로 돌아옵니다.
| 항목 | 값 | 근거 |
|---|---|---|
| 빈 구독 조회 시 최대 대기 시간 | 기본 2초 (2~20초) | timeout 옵션 |
| 한 응답의 최대 건수/크기 | 1,000건/10MB | 할당량 및 한도 |
| 반환 실패 시 복귀 시간 | 구독의 확인 기한 (기본 10초) | 구독 속성 |
알아두어야 할 점
반환 건수는 호출마다 달라집니다. limit은 상한일 뿐입니다. REST 레퍼런스도 "The Pub/Sub system may return fewer than the number specified"라고 명시합니다. 구독에 1,000건이 쌓여 있어도 수십 건만 반환될 수 있으므로, 전체를 확인하려면 여러 번 실행하십시오.
빈 결과가 곧 구독이 비었다는 뜻은 아닙니다. Pull 구독 문서는 "A response with zero messages or with an error does not necessarily indicate that there are no messages available to receive"라고 밝힙니다. timeout 값이 작을수록 자주 발생하므로, 값을 늘려 다시 실행하십시오.
관련 명령어
메시지를 실제로 소비하며 실시간으로 수신하려면 gcp-pubsub-messages를 사용하십시오.