Meta 인사이트 배치 즉시 실행

production 환경에서 매시간 정각 자동 실행되는 일별 적재 배치를 즉시 1회 실행합니다. 최근 90일(D-1 ~ D-90)을 광고 계정 트리(캠페인/광고세트/광고)와 함께 일별 인사이트로 갱신하고, 광고 creative 이미지/비디오 cover 도 S3 에 백업합니다.

멱등 보장(UK upsert). 같은 날 여러 번 실행해도 데이터가 중복되지 않고 덮어쓰기됩니다.

멀티 광고계정 처리 — accountId 미지정 시 활성 광고계정 5개(글로우비 / 디웨더 / 리빙 / Supera / 건식건기식) 를 순차 처리합니다 (계정 간 5초 cooldown). 1개 계정만 처리하려면 ?accountId=act_xxx 지정.

HTTP 요청

POST /ai/admin/meta-insight/batch/run
Authorization: Bearer {admin_access_token}

Query Parameters

파라미터	기본값	설명
`accountId`	(없음)	특정 광고계정만 실행 (`act_xxx`). 미지정 시 활성 광고계정 전체 순회

예시

# 5계정 전체 순회
POST /ai/admin/meta-insight/batch/run

# 디웨더만 실행
POST /ai/admin/meta-insight/batch/run?accountId=act_1160065922750394

응답

성공 응답 (200 OK)

{
  "status": 200,
  "code": null,
  "message": "배치 실행 완료",
  "data": {
    "skipped": false,
    "totalCalls": 6,
    "failedCalls": 0,
    "upsertedSnapshots": 23,
    "upsertedInsights": 1820,
    "failedRows": 0
  }
}

응답 필드

필드	설명
`triggerId`	UUID. 서버 로그에서 이 ID 로 grep 하면 해당 배치의 진행 상황 추적 가능
`status`	항상 `STARTED` (비동기 시작 알림)

결과 확인 방법

배치는 백엔드에서 5계정 순회 시 ~15분 정도 진행됩니다. 서버 로그에서 다음 라인들을 확인:

[Meta batch][{triggerId}] async start — admin-triggered (all accounts)
[Meta batch][account=act_2916260795344961] start (1/5) — name='글로우비'
[Meta batch][account=act_2916260795344961] step 1/2: tree sync
[Meta batch][account=act_2916260795344961] App call=12% cpu=8% time=5%
[Meta batch][account=act_2916260795344961] BUC type=ads_management call=23% cpu=18% time=11%
[Meta batch][account=act_2916260795344961] step 1/2 done — campaigns=217, adsets=240, ads=350
[Meta batch][account=act_2916260795344961] step 2/2 (1/4) level=ACCOUNT rows added=89
... (광고계정별 반복)
[Meta batch][account=act_1160065922750394] start (2/5) — name='디웨더'
... 
[Meta batch][{triggerId}] async finished — { ...분해 카운터 전체... }

Rate Limit 헤더 로그

매 Meta API 호출 응답 헤더를 파싱해 로그에 기록합니다 (자동 차단/백오프는 1차 미적용, 가시성 확보가 목적):

헤더	의미	로그 prefix
`X-App-Usage`	앱(토큰) 단위 quota — 5계정 호출 모두 합산	`App call=X% cpu=Y% time=Z%`
`X-Business-Use-Case-Usage`	광고계정별 BUC quota (계정마다 독립)	`BUC type=... call=X% cpu=Y% time=Z%`

운영 가이드: App 사용률이 자주 70% 이상이면 standard_access 승급 또는 adset/ad 레벨 호출 빈도 조정 검토. BUC 가 특정 계정만 자주 70% 이상이면 inactive backfill stagger 시간 분리 검토.

에러 응답

상태 코드	설명
`403`	관리자 권한 없음

권한

ADMIN 전용

POST /ai/admin/meta-insight/batch/run