데이터 전달
신선도는 요청 파라미터입니다.
모든 데이터 엔드포인트는 freshness(cache | default | live)와 max_age(초)를 받습니다. 호출마다 선택하세요: 저렴한 캐시 읽기로 고정하거나, 플랫폼의 신선도 윈도우에 맡기거나, 새로운 업스트림 가져오기를 강제할 수 있습니다. 모든 응답은 어떤 계층이 응답했는지와 과금액을 정확히 보고합니다.
3가지 전략, 하나의 파라미터
freshness=cache
플랫폼 캐시에서만 응답합니다 — 이 모드에서는 획득 파이프라인에 구조적으로 도달할 수 없습니다.
- 지연 시간
- 가장 빠름: 캐시 읽기 1회, 업스트림 홉 없음.
- 과금
- 해당 캐퍼빌리티의 캐시 티어 Credits — 대부분의 캐퍼빌리티에서 기본 가격의 절반.
- 미스 / 실패 시
- 404 DATA_NOT_FOUND. 업스트림을 호출하지 않고 대신 가져오지도 않습니다.
freshness=default
플랫폼이 신선도 윈도우 안에서 판단합니다: 신선한 캐시는 즉시 응답하고, 만료된 항목은 stale로 응답하면서 중복 제거된 백그라운드 갱신을 실행하며, 없으면 업스트림에서 가져옵니다.
- 지연 시간
- 캐시 히트: 빠름. 업스트림 획득: 업스트림 왕복 1회(동시 호출자가 공유).
- 과금
- 캐시 응답(stale+갱신 포함)은 캐시 티어, 신규 획득과 엔티티 스토어 히트는 기본 가격.
- 미스 / 실패 시
- 획득 파이프라인으로 자동 폴백 — 모든 공급자가 실패하지 않는 한(502 UPSTREAM_ERROR) 미스는 보이지 않습니다.
freshness=live
캐시와 엔티티 스토어를 완전히 건너뛰고 공급자를 호출해 최신 데이터를 가져온 뒤 캐시에 다시 기록합니다.
- 지연 시간
- 항상 전체 업스트림 왕복 — 설계상 가장 느린 경로입니다.
- 과금
- 기본 가격. 요금 규칙에 live 배수가 설정된 캐퍼빌리티는 그 배수를 따릅니다.
- 미스 / 실패 시
- live 가져오기 실패 시 502 UPSTREAM_ERROR를 반환합니다 — 오래된 데이터를 신선한 척하지 않습니다.
나란히 비교
| 항목 | cache | default | live |
|---|---|---|---|
| 데이터 소스 | 플랫폼 캐시만 | 캐시 → 엔티티 스토어 → 공급자 | 항상 공급자 |
| 지연 시간 | 최저 — 업스트림 홉 없음 | 캐시 히트 시 낮음. 획득 시 업스트림 왕복 | 매 호출 업스트림 왕복 |
| 과금 | 캐시 티어 Credits | 캐시 응답은 캐시 티어, 획득은 기본 가격 | 기본 가격 |
| 미스 시 | 404 DATA_NOT_FOUND | 업스트림에서 획득 | 502 UPSTREAM_ERROR |
max_age: 호출별 신선도 윈도우
max_age는 캐시/저장 항목의 허용 나이(초)를 제한합니다. 우선순위: freshness > max_age > 플랫폼 고유 TTL 윈도우. max_age=0으로 이번 호출에서 가져오지 않은 데이터를 모두 거부할 수 있습니다.
GET /v1/x/users/newdev?max_age=300 # serve cache/db entries at most 5 minutes old; # anything older triggers acquisition (default mode)
모든 응답이 무슨 일이 있었는지 알려줍니다
meta.freshness는 실효 모드, 데이터 나이(초), 응답 계층(cache | db | upstream), 만료 항목을 stale로 응답했는지를 보고합니다. meta.billing은 청구된 Credits와 캐시 히트 여부를 보고합니다 — 사후 추측이 필요 없습니다.
"meta": {
"freshness": { "mode": "default", "age_seconds": 781,
"source_layer": "cache", "stale": false },
"billing": { "amount_credits": 100, "cache_hit": true }
}콘솔의 사용 원장은 같은 숫자를 호출별로 분해하므로, 한 달 트래픽을 행 단위로 대조할 수 있습니다.