⚙️ [기능추가][인스타] 인스타 게시글에 대한 메타데이터, 이미지, 캡션 추출 로직 추가

[Cassiiopeia]

📝 현재 문제점

• scapefly 필요없이 공개적 인스타에서 추출하는 로직이 필요합니다

🛠️ 해결 방안 / 제안 기능

• 최대한 많은 정보를 출력할수있음 좋습니다

🙋‍♂️ 담당자

• 백엔드: @Cassiiopeia
• 프론트엔드: 이름
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260111_#3_인스타_게시글에_대한_메타데이터_이미지_캡션_추출_로직_추가

커밋 메시지

인스타 게시글에 대한 메타데이터, 이미지, 캡션 추출 로직 추가 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSee-AI/issues/3

[Cassiiopeia]

@suh-lab server build

[github-actions]

✅ Issue Preview 배포 완료!

브랜치: 20260111_#3_인스타_게시글에_대한_메타데이터_이미지_캡션_추출_로직_추가

단계	상태	소요 시간
🐳 Docker 이미지 빌드 & Push	✅ 완료	1분 27초
🚀 서버 배포 & Health Check	✅ 완료	1분 11초

🌐 Preview 환경

항목	값
Preview URL	http://mapsee-ai-pr-3.pr.suhsaechan.kr:8079
Swagger Docs	http://mapsee-ai-pr-3.pr.suhsaechan.kr:8079/docs/swagger
컨테이너	mapsee-ai-pr-3
브랜치	20260111_#3_인스타_게시글에_대한_메타데이터_이미지_캡션_추출_로직_추가

📋 명령어

명령어	설명
@suh-lab server build	최신 커밋으로 재배포
@suh-lab server destroy	Preview 환경 삭제
@suh-lab server status	현재 상태 확인

---

🤖 이 댓글은 Issue Preview 시스템에 의해 자동 생성되었습니다.

[Cassiiopeia]

https://sociavault.com/blog/scrape-instagram-without-getting-blocked

[Cassiiopeia]

구현 보고서: Instagram 메타데이터, 이미지, 캡션 추출 로직

이슈: #3
작업일: 2026-01-11
브랜치: 20260111_#3_인스타_게시글에_대한_메타데이터_이미지_캡션_추출_로직_추가

---

📌 작업 개요

Instagram 게시글 URL을 입력받아 Playwright로 메타데이터(캡션, 좋아요 수, 댓글 수, 작성자, 게시일, 해시태그)와 이미지 URL을 추출하는 스크래핑 로직 구현. URL 분류를 통해 플랫폼(Instagram/YouTube)과 콘텐츠 타입(post/reel/video/shorts)을 자동 감지하며, 확장 가능한 구조로 설계.

---

🎯 구현 목표

• Instagram 게시글에서 메타데이터 추출 (og 태그 기반)
• 게시글 이미지 URL 추출 (cdninstagram.com 도메인)
• URL 분류 로직으로 플랫폼/콘텐츠 타입 자동 감지
• YouTube 스텁 준비 (501 Not Implemented 반환)
• 명확한 파일 네이밍과 확장 가능한 폴더 구조

---

✅ 구현 내용

1. 스크래퍼 모듈 구조 생성

새로 생성된 폴더 구조:

src/services/scraper/
├── __init__.py
├── playwright_browser.py      # Playwright 브라우저 공통 제어
├── scrape_router.py           # URL → 플랫폼별 스크래퍼 라우팅
└── platforms/
    ├── __init__.py
    ├── instagram_scraper.py   # Instagram 스크래핑 로직
    └── youtube_scraper.py     # YouTube 스텁 (501 반환)

2. Playwright 브라우저 공통 모듈

• 파일: src/services/scraper/playwright_browser.py
• 변경 내용: 브라우저 생성, 페이지 로드, og 메타 태그 추출, 브라우저 종료 로직을 공통 클래스로 분리
• 이유: Instagram, YouTube 등 여러 플랫폼에서 재사용 가능한 공통 로직 분리

주요 메서드:

• create_browser_and_context(): Chromium 브라우저 + 컨텍스트 생성
• load_page(): URL 로드 및 networkidle 대기
• extract_open_graph_tags(): og:title, og:description, og:image, og:url 추출
• close_browser(): 리소스 정리

3. Instagram 스크래퍼 구현

• 파일: src/services/scraper/platforms/instagram_scraper.py
• 변경 내용: og:description 파싱하여 메타데이터 추출, cdninstagram.com 이미지 URL 추출
• 이유: Instagram 게시글의 메타데이터를 정형화된 구조로 반환

추출되는 메타데이터:

필드	설명	예시
platform	플랫폼명	"instagram"
content_type	콘텐츠 타입	"post", "reel", "igtv"
author	작성자	"jamsilism"
caption	캡션 본문	게시글 텍스트
likes_count	좋아요 수	7434
comments_count	댓글 수	63
posted_at	게시일	"September 24, 2025"
hashtags	해시태그 목록	["#잠실", "#맛집"]
og_image	og:image URL	CDN URL
image_urls	이미지 URL 목록	CDN URL 배열

og:description 파싱 로직:

입력: "7,434 likes, 63 comments - jamsilism on September 24, 2025: "캡션...""
      ↓ 정규식 파싱
출력: { likes_count: 7434, comments_count: 63, author: "jamsilism", posted_at: "September 24, 2025", caption: "캡션..." }

4. URL 분류 로직 개선

• 파일: src/utils/url_classifier.py
• 변경 내용: YouTube URL 분류 추가 (video, shorts 구분)
• 이유: YouTube URL도 분류하여 적절한 스크래퍼로 라우팅

지원 URL 패턴:

플랫폼	패턴	content_type
Instagram	/p/	post
Instagram	/reel/, /reels/	reel
Instagram	/tv/	igtv
YouTube	/shorts/	shorts
YouTube	기타	video

5. 스크래핑 라우터

• 파일: src/services/scraper/scrape_router.py
• 변경 내용: URL 분류 결과에 따라 적절한 플랫폼 스크래퍼로 라우팅
• 이유: 확장성 있는 구조로 새 플랫폼 추가 용이

6. YouTube 스텁 생성

• 파일: src/services/scraper/platforms/youtube_scraper.py
• 변경 내용: 501 Not Implemented 반환하는 스텁 생성
• 이유: YouTube 스크래핑 요청 시 명확한 "미구현" 응답 제공

7. 테스트 API 라우터 수정

• 파일: src/apis/test_router.py
• 변경 내용: 새로운 스크래퍼 모듈 import로 변경
• 이유: 리팩토링된 구조에 맞게 의존성 업데이트

8. CLAUDE.md 네이밍 규칙 추가

• 파일: CLAUDE.md
• 변경 내용: 파일명/변수명 네이밍 규칙 섹션 추가
• 이유: 명확한 네이밍 컨벤션 문서화

---

🔧 주요 변경사항 상세

playwright_browser.py

Playwright 브라우저 제어를 위한 공통 클래스. User-Agent를 Chrome으로 설정하고, 1920x1080 뷰포트 사용. networkidle 대기로 동적 콘텐츠 로딩 보장.

instagram_scraper.py

og:description에서 정규식으로 메타데이터 파싱. cdninstagram.com 도메인 이미지 중 프로필 이미지(150x150, 44x44) 제외하고 추출. 중복 URL 자동 제거.

특이사항:

• og:description 형식이 Instagram 버전에 따라 달라질 수 있음
• 정규식 패턴이 현재 Instagram 형식에 맞춰져 있으며, 향후 변경 시 수정 필요

url_classifier.py

urlparse로 도메인/경로 분석 후 플랫폼과 콘텐츠 타입 반환. 지원하지 않는 URL은 400 에러 발생.

---

📦 의존성 변경

• 추가: playwright (pyproject.toml)
• 필요 작업: playwright install chromium 실행 필요

---

🧪 테스트 및 검증

Instagram 테스트

curl -X POST http://localhost:8001/api/test/scrape \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.instagram.com/p/DO-u-YwD6Rt/"}'

예상 결과: 200 OK + 메타데이터 JSON

YouTube 테스트 (501 확인)

curl -X POST http://localhost:8001/api/test/scrape \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=xxx"}'

예상 결과: 501 Not Implemented + "YouTube 스크래핑은 아직 구현되지 않았습니다"

지원하지 않는 URL 테스트

curl -X POST http://localhost:8001/api/test/scrape \
  -H "Content-Type: application/json" \
  -d '{"url": "https://twitter.com/xxx"}'

예상 결과: 400 Bad Request + "지원하지 않는 플랫폼: twitter.com"

---

📂 변경/생성 파일 목록

파일	작업
CLAUDE.md	수정 - 네이밍 규칙 추가
src/services/scraper/__init__.py	생성
src/services/scraper/playwright_browser.py	생성 - 브라우저 공통 로직
src/services/scraper/scrape_router.py	생성 - 스크래핑 라우터
src/services/scraper/platforms/__init__.py	생성
src/services/scraper/platforms/instagram_scraper.py	생성 - Instagram 스크래퍼
src/services/scraper/platforms/youtube_scraper.py	생성 - YouTube 스텁
src/utils/url_classifier.py	수정 - YouTube 분류 추가
src/apis/test_router.py	수정 - import 경로 변경
src/services/preprocess/playwright_scraper.py	삭제 - 새 구조로 이전

---

📌 참고사항

• Instagram 로그인 필요 없음: og 메타 태그는 로그인 없이 접근 가능
• Rate Limiting: Instagram에서 과도한 요청 시 차단될 수 있으므로 프로덕션에서는 요청 간격 조절 필요
• 이미지 URL 만료: cdninstagram.com URL은 시간이 지나면 만료될 수 있음
• YouTube 구현 예정: 현재 501 스텁만 있으며, 향후 yt-dlp 또는 YouTube API로 구현 예정

[Cassiiopeia]