Apify 자동화
Claude Code에서 직접 Apify 웹 스크래핑 Actor를 실행하고 데이터셋을 관리하세요. 동기식 또는 비동기식으로 크롤러를 실행하고, 구조화된 데이터를 검색하며, 재사용 가능한 작업을 만들고, 터미널을 떠나지 않고 실행 로그를 확인할 수 있습니다.
툴킷 문서: composio.dev/toolkits/apify
설정
- Composio MCP 서버를 설정에 추가하세요:
https://rube.app/mcp - 메시지가 표시되면 Apify 계정을 연결하세요. 에이전트가 인증 링크를 제공합니다.
- apify.com/store에서 사용 가능한 Actor를 탐색하세요. 각 Actor는 고유한 입력 스키마를 가지고 있습니다. 실행하기 전에 항상 Actor의 문서를 확인하세요.
핵심 워크플로우
1. Actor를 동기식으로 실행하고 결과 받기
Actor를 실행하고 단일 호출로 데이터셋 항목을 즉시 검색합니다. 빠른 스크래핑 작업에 가장 적합합니다.
도구: APIFY_RUN_ACTOR_SYNC_GET_DATASET_ITEMS
주요 매개변수:
actorId(필수) --username/actor-name형식의 Actor ID (예:compass/crawler-google-places)input-- Actor의 스키마와 일치하는 JSON 입력 객체. 각 Actor는 고유한 필드 이름을 가집니다. 정확한 스키마는 apify.com/store를 확인하세요.limit-- 반환할 최대 항목 수offset-- 페이지네이션을 위해 건너뛸 항목 수format--json(기본값),csv,jsonl,html,xlsx,xmltimeout-- 실행 제한 시간(초)waitForFinish-- 최대 대기 시간 (0-300초)fields-- 포함할 쉼표로 구분된 필드 목록omit-- 제외할 쉼표로 구분된 필드 목록
예시 프롬프트: "Google Places 스크래퍼를 '뉴욕 맛집'으로 실행하고 처음 50개 결과를 반환해줘"
2. Actor를 비동기식으로 실행하기
완료를 기다리지 않고 Actor 실행을 트리거합니다. 장기 실행 스크래핑 작업에 사용합니다.
도구: APIFY_RUN_ACTOR
주요 매개변수:
actorId(필수) -- Actor 슬러그 또는 IDbody-- Actor에 대한 JSON 입력 객체memory-- 메모리 제한(MB). 2의 거듭제곱이어야 하며 최소 128입니다.timeout-- 실행 제한 시간(초)maxItems-- 반환 항목 상한선build-- 특정 빌드 태그 (예:latest,beta)
실행의 datasetId를 사용하여 결과를 검색하려면 APIFY_GET_DATASET_ITEMS로 후속 작업을 수행하세요.
예시 프롬프트: "example.com용 웹 스크래퍼 Actor를 1024MB 메모리로 비동기식으로 시작해줘"
3. 데이터셋 항목 검색
페이지네이션, 필드 선택 및 필터링을 사용하여 특정 데이터셋에서 데이터를 가져옵니다.
도구: APIFY_GET_DATASET_ITEMS
주요 매개변수:
datasetId(필수) -- 데이터셋 식별자limit(기본값/최대 1000) -- 페이지당 항목 수offset(기본값 0) -- 페이지네이션 오프셋format--json(권장),csv,xlsxfields-- 특정 필드만 포함omit-- 특정 필드 제외clean-- Apify 관련 메타데이터 제거desc-- 역순으로 정렬 (최신 항목 먼저)
예시 프롬프트: "데이터셋 myDatasetId에서 처음 500개 항목을 JSON 형식으로 가져와줘"
4. Actor 세부 정보 확인
Actor를 실행하기 전에 Actor 메타데이터, 입력 스키마 및 구성을 확인합니다.
도구: APIFY_GET_ACTOR
주요 매개변수:
actorId(필수) --username/actor-name형식 또는 16진수 ID의 Actor ID
예시 프롬프트: "apify/web-scraper Actor의 세부 정보와 입력 스키마를 보여줘"
5. 재사용 가능한 작업 생성
반복적인 스크래핑 작업을 위해 사전 설정된 입력으로 재사용 가능한 Actor 작업을 구성합니다.
도구: APIFY_CREATE_TASK
작업을 한 번 구성한 다음 일관된 입력 매개변수로 반복적으로 트리거합니다. 예약되거나 반복적인 데이터 수집 워크플로우에 유용합니다.
예시 프롬프트: "Google 검색 스크래퍼를 위한 Apify 작업을 기본 쿼리 'AI 스타트업' 및 미국 위치로 생성해줘"
6. 실행 및 데이터셋 관리
Actor 실행 목록을 보고, 데이터셋을 탐색하며, 모니터링 및 디버깅을 위해 실행 세부 정보를 확인합니다.
도구: APIFY_GET_LIST_OF_RUNS, APIFY_DATASETS_GET, APIFY_DATASET_GET, APIFY_GET_LOG
실행 목록 조회:
- Actor별로 필터링하고 선택적으로 상태별로 필터링
- 데이터 검색을 위해 실행 세부 정보에서
datasetId가져오기
데이터셋 관리:
APIFY_DATASETS_GET-- 페이지네이션으로 모든 데이터셋 나열APIFY_DATASET_GET-- 특정 데이터셋의 메타데이터 가져오기
디버깅:
APIFY_GET_LOG-- 실행 또는 빌드의 실행 로그 검색
예시 프롬프트: "웹 스크래퍼 Actor의 마지막 10개 실행을 나열하고 가장 최근 실행의 로그를 보여줘"
알려진 문제점
- Actor 입력 스키마는 매우 다양합니다: 모든 Actor는 고유한 입력 필드를 가집니다.
queries나search_terms와 같은 일반적인 필드 이름은 거부됩니다. 정확한 필드 이름(예: Google Maps의 경우searchStringsArray, 웹 스크래퍼의 경우startUrls)은 항상 apify.com/store의 Actor 페이지를 확인하세요. - URL 형식 요구 사항: URL에는 항상 전체 프로토콜(
https://또는http://)을 포함하세요. 많은 Actor는url속성이 있는 객체로 URL을 요구합니다:{"startUrls": [{"url": "https://example.com"}]}. - 데이터셋 페이지네이션 제한:
APIFY_GET_DATASET_ITEMS는 호출당 최대limit값이 1000입니다. 대규모 데이터셋의 경우offset으로 반복하여 모든 항목을 수집하세요. - 열거형 값은 소문자입니다: 대부분의 Actor는 소문자 열거형 값을 예상합니다 (예:
RELEVANCE가 아닌relevance,ALL이 아닌all). - 동기 실행 타임아웃 5분:
APIFY_RUN_ACTOR_SYNC_GET_DATASET_ITEMS의 최대waitForFinish는 300초입니다. 더 긴 실행의 경우APIFY_RUN_ACTOR(비동기)를 사용하고APIFY_GET_DATASET_ITEMS로 폴링하세요. - 데이터 볼륨 비용: 대규모 데이터셋은 가져오는 데 비용이 많이 들 수 있습니다. 타임아웃이나 메모리 압력을 피하려면 적당한 제한과 증분 처리를 선호하세요.
- JSON 형식 권장: CSV/XLSX 형식을 사용할 수 있지만, JSON은 자동화된 처리에 가장 안정적입니다. 다운스트림 자동화의 경우 CSV/XLSX를 피하세요.
빠른 참조
| 도구 슬러그 | 설명 |
|---|---|
APIFY_RUN_ACTOR_SYNC_GET_DATASET_ITEMS | Actor를 동기식으로 실행하고 즉시 결과 가져오기 |
APIFY_RUN_ACTOR | Actor를 비동기식으로 실행 (트리거 및 반환) |
APIFY_RUN_ACTOR_SYNC | Actor를 동기식으로 실행, 출력 레코드 반환 |
APIFY_GET_ACTOR | Actor 메타데이터 및 입력 스키마 가져오기 |
APIFY_GET_DATASET_ITEMS | 데이터셋에서 항목 검색 (페이지네이션) |
APIFY_DATASET_GET | 데이터셋 메타데이터 가져오기 (항목 수 등) |
APIFY_DATASETS_GET | 모든 사용자 데이터셋 나열 |
APIFY_CREATE_TASK | 재사용 가능한 Actor 작업 생성 |
APIFY_GET_TASK_INPUT | 작업의 저장된 입력 확인 |
APIFY_GET_LIST_OF_RUNS | Actor의 실행 목록 |
APIFY_GET_LOG | 실행 로그 가져오기 |
Composio 제공