> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Apify의 웹 스크래핑 및 자동화 데이터를 ClickHouse로 적재합니다

# Apify를 ClickHouse에 연결하기

export const CommunityMaintainedBadge = () => {
  return <div className="CommunityMaintainedBadge">
            <div className="CommunityMaintainedIcon">
            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 256 256">
                <path d="M244.8,150.4a8,8,0,0,1-11.2-1.6A51.6,51.6,0,0,0,192,128a8,8,0,0,1-7.37-4.89,8,8,0,0,1,0-6.22A8,8,0,0,1,192,112a24,24,0,1,0-23.24-30,8,8,0,1,1-15.5-4A40,40,0,1,1,219,117.51a67.94,67.94,0,0,1,27.43,21.68A8,8,0,0,1,244.8,150.4ZM190.92,212a8,8,0,1,1-13.84,8,57,57,0,0,0-98.16,0,8,8,0,1,1-13.84-8,72.06,72.06,0,0,1,33.74-29.92,48,48,0,1,1,58.36,0A72.06,72.06,0,0,1,190.92,212ZM128,176a32,32,0,1,0-32-32A32,32,0,0,0,128,176ZM72,120a8,8,0,0,0-8-8A24,24,0,1,1,87.24,82a8,8,0,1,0,15.5-4A40,40,0,1,0,37,117.51,67.94,67.94,0,0,0,9.6,139.19a8,8,0,1,0,12.8,9.61A51.6,51.6,0,0,1,64,128,8,8,0,0,0,72,120Z"></path>
            </svg>
        </div>
            커뮤니티에서 관리
        </div>;
};

<CommunityMaintainedBadge />

[Apify](https://apify.com/)는 웹 스크래핑 및 자동화 플랫폼입니다. [**Actor**](https://docs.apify.com/platform/actors)라고 하는 서버리스 클라우드 프로그램을 구축, 실행, 확장할 수 있습니다. Actor는 웹사이트를 스크레이프하고, 웹을 크롤링하며, 데이터를 처리하거나 워크플로를 자동화합니다. Actor를 실행할 때마다 구조화된 출력이 생성되며, 이 출력은 [**데이터셋**](https://docs.apify.com/platform/storage/dataset)(JSON 객체 모음)에 저장됩니다.

스크레이프했거나 처리한 데이터를 분석, 모니터링 또는 보강 파이프라인에 활용하기 위해 ClickHouse에 적재합니다.

<div id="key-concepts">
  ## 핵심 개념
</div>

| Apify 개념                                                             | 설명                                                                                                                                 |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **[Actor](https://docs.apify.com/platform/actors)**                  | Apify 플랫폼에서 실행되는 서버리스 클라우드 프로그램입니다. [Apify Store](https://apify.com/store)에서는 바로 사용할 수 있는 수천 개의 Actor를 제공합니다.                      |
| **[Dataset](https://docs.apify.com/platform/storage/dataset)**       | Actor 실행 결과물입니다. JSON 객체로 구성된 테이블 형태의 데이터셋이며, [Apify API](https://docs.apify.com/api/v2)를 통해 JSON, CSV, XML 또는 기타 포맷으로 가져올 수 있습니다. |
| **[Webhook](https://docs.apify.com/platform/integrations/webhooks)** | Actor 실행이 성공, 실패하거나 기타 수명 주기 이벤트에 도달할 때 트리거되는 이벤트 기반 HTTP 호출입니다. 웹훅을 사용해 Apify-to-ClickHouse 파이프라인을 자동화할 수 있습니다.                   |

<div id="setup-guide">
  ## 설정 가이드
</div>

<Steps>
  <Step title="ClickHouse 연결 정보를 확인하세요" id="1-gather-your-connection-details">
    HTTP(S)로 ClickHouse에 연결하려면 다음 정보가 필요합니다.

    | 매개변수                      | 설명                                                         |
    | ------------------------- | ---------------------------------------------------------- |
    | `HOST` and `PORT`         | 일반적으로 TLS를 사용하는 경우 포트는 8443, TLS를 사용하지 않는 경우 8123입니다.      |
    | `DATABASE NAME`           | 기본적으로 `default`라는 이름의 데이터베이스가 제공되며, 연결할 데이터베이스 이름을 사용하십시오. |
    | `USERNAME` and `PASSWORD` | 기본 사용자 이름은 `default`입니다. 사용 사례에 맞는 사용자 이름을 사용하십시오.         |

    ClickHouse Cloud 서비스의 연결 정보는 ClickHouse Cloud 콘솔에서 확인할 수 있습니다.
    서비스를 선택한 다음 **Connect**를 클릭하십시오.

    <div className="ch-image-md">
      <Frame>
        <img src="https://mintcdn.com/private-7c7dfe99/CFFsa2agBPbviR4r/images/_snippets/cloud-connect-button.webp?fit=max&auto=format&n=CFFsa2agBPbviR4r&q=85&s=ec0a298a33ca841e947fa5e8bae47362" alt="ClickHouse Cloud 서비스 연결 버튼" width="998" height="932" data-path="images/_snippets/cloud-connect-button.webp" />
      </Frame>
    </div>

    **HTTPS**를 선택하십시오. 연결 정보가 예시 `curl` 명령으로 표시됩니다.

    <div className="ch-image-md">
      <Frame>
        <img src="https://mintcdn.com/private-7c7dfe99/CFFsa2agBPbviR4r/images/_snippets/connection-details-https.webp?fit=max&auto=format&n=CFFsa2agBPbviR4r&q=85&s=cb0fbd98aa2b5b7ca484c9f53395ee07" alt="ClickHouse Cloud HTTPS 연결 정보" width="1320" height="1184" data-path="images/_snippets/connection-details-https.webp" />
      </Frame>
    </div>

    자가 관리형 ClickHouse를 사용하는 경우 연결 정보는 ClickHouse 관리자가 설정합니다.
  </Step>

  <Step title="Apify 사전 요구 사항" id="2-apify-prerequisites">
    추가로 다음이 필요합니다:

    * [Apify 계정](https://console.apify.com/sign-up) (무료 tier 사용 가능).
    * [Apify API token](https://docs.apify.com/platform/integrations/api#api-token) — [Apify Console](https://console.apify.com/)의 **Settings > Integrations**에서 확인할 수 있습니다.
    * 로컬에 설치된 Node.js 18+ (JavaScript 예시용).
  </Step>

  <Step title="종속성 설치" id="3-install-dependencies">
    Apify JavaScript client와 ClickHouse JavaScript client를 설치합니다:

    ```bash theme={null}
    npm install apify-client @clickhouse/client
    ```

    <Note>
      Apify는 [Python client](https://docs.apify.com/api/client/python)도 제공합니다. Python을 선호한다면 pip로 `apify-client`를 설치하고, ClickHouse에는 [clickhouse-connect](/docs/ko/integrations/language-clients/python/index)를 사용하십시오.
    </Note>
  </Step>

  <Step title="ClickHouse에 대상 테이블을 생성하세요" id="4-create-a-target-table">
    스크레이프한 데이터를 저장할 테이블을 생성합니다. 스키마는 사용하는 Actor에 따라 달라집니다. 이 예시에서는 제품 스크레이핑 Actor용으로 [MergeTree](/docs/ko/reference/engines/table-engines/mergetree-family/mergetree)를 사용합니다:

    ```sql theme={null}
    CREATE TABLE apify_products
    (
        url        String,
        title      String,
        price      Float64,
        currency   String,
        scraped_at DateTime DEFAULT now()
    )
    ENGINE = MergeTree()
    ORDER BY (scraped_at, url);
    ```
  </Step>

  <Step title="Apify 데이터셋을 가져와 ClickHouse에 적재하세요" id="5-fetch-and-load">
    다음 스크립트는 Apify Actor 실행 결과를 가져와 ClickHouse에 삽입합니다:

    ```javascript theme={null}
    import { ApifyClient } from 'apify-client';
    import { createClient } from '@clickhouse/client';

    // 클라이언트 초기화
    const apify = new ApifyClient({ token: 'YOUR_APIFY_API_TOKEN' });
    const clickhouse = createClient({
        url: 'https://YOUR_CLICKHOUSE_HOST:8443',
        username: 'default',
        password: 'YOUR_CLICKHOUSE_PASSWORD',
        database: 'default',
    });

    // Actor의 마지막 실행에서 데이터셋 항목 가져오기
    const run = await apify.actor('YOUR_ACTOR_ID').call();
    const { items } = await apify.dataset(run.defaultDatasetId).listItems();

    console.log(`Fetched ${items.length} items from Apify dataset.`);

    // ClickHouse에 삽입
    await clickhouse.insert({
        table: 'apify_products',
        values: items,
        format: 'JSONEachRow',
    });

    console.log(`Inserted ${items.length} rows into ClickHouse.`);
    await clickhouse.close();
    ```

    <Tip>
      대규모 데이터셋의 경우 [List dataset items](https://docs.apify.com/api/v2#/reference/datasets/item-collection/list-items) endpoint의 `limit` 및 `offset` 매개변수를 사용해 결과를 페이지 단위로 가져오십시오. `clean=true`를 전달하면 비어 있지 않고 중복이 제거된 항목만 가져올 수도 있습니다.
    </Tip>
  </Step>

  <Step title="웹훅으로 자동화하세요" id="6-automate-with-webhooks">
    스크립트를 수동으로 실행하는 대신, Actor가 완료될 때마다 데이터가 ClickHouse에 적재되도록 파이프라인을 자동화합니다:

    1. [Apify Console](https://console.apify.com/)에서 Actor로 이동한 다음 **Integrations** 탭을 엽니다.
    2. 다음과 같이 새 웹훅을 추가합니다:
       * **Event type:** `ACTOR.RUN.SUCCEEDED`
       * **Action:** 로더 endpoint로 HTTP POST를 보내거나, ClickHouse 삽입을 처리하는 다른 Actor를 트리거합니다.
    3. 웹훅 payload에는 `defaultDatasetId`가 포함되며, 이를 사용해 실행 결과를 가져올 수 있습니다.

    payload 세부 정보와 구성 옵션은 [Apify 웹훅 documentation](https://docs.apify.com/platform/integrations/webhooks)을 참고하십시오.

    대안으로는 [Apify Schedules](https://docs.apify.com/platform/schedules)를 사용해 cron과 유사한 일정으로 Actor를 실행하고, 적재 단계에는 웹훅을 함께 사용할 수도 있습니다.
  </Step>
</Steps>

<div id="best-practices">
  ## 모범 사례
</div>

<div id="fetching-data-from-apify">
  ### Apify에서 데이터 가져오기
</div>

직접 HTTP 호출을 사용하는 대신 Apify 클라이언트 라이브러리([JavaScript](https://docs.apify.com/api/client/js)용 `apify-client` 또는 [Python](https://docs.apify.com/api/client/python))를 사용하십시오. 이 라이브러리는 페이지네이션, 재시도, 인증을 대신 처리해 줍니다. 대규모 데이터셋의 경우 [List dataset items](https://docs.apify.com/api/v2#/reference/datasets/item-collection/list-items) endpoint의 `limit` 및 `offset` 매개변수를 사용해 결과를 페이지별로 조회하십시오.

<div id="loading-into-clickhouse">
  ### ClickHouse에 적재하기
</div>

ClickHouse에 삽입할 때는 [`JSONEachRow`](/docs/ko/reference/formats/JSON/JSONEachRow) 포맷을 사용하십시오. Apify의 JSON 출력과 직접 대응하므로 별도의 변환이 필요하지 않습니다.

ClickHouse 테이블 스키마를 Actor의 출력 필드에 맞추십시오. Actor의 출력 스키마는 [Apify Store](https://apify.com/store) 페이지 또는 실행 후 **Dataset** 탭에서 확인할 수 있습니다.

<div id="performance">
  ### 성능
</div>

JavaScript client에서 높은 처리량으로 데이터를 삽입하려면 [성능 최적화를 위한 팁](/docs/ko/integrations/language-clients/js/index#tips-for-performance-optimizations)을 따르십시오. 행을 한 번에 하나씩 삽입하는 대신 여러 행을 묶어 더 큰 단위로 삽입하고, 클라이언트 측 배칭이 실용적이지 않은 경우 [async inserts](/docs/ko/concepts/features/operations/insert/asyncinserts)를 고려하십시오.

<div id="security">
  ### 보안
</div>

이 페이지의 예시는 설명을 단순하게 하기 위해 `default` 사용자와 데이터베이스를 사용합니다. 프로덕션 환경에서는 대상 테이블(target table)에 삽입하는 데 필요한 최소 권한만 가진 전용 사용자를 생성하고, 자격 증명은 안전하게 저장하십시오(예: 소스 코드에 커밋하지 말고 환경 변수나 시크릿 관리 도구에 저장). 자세한 내용은 [Cloud 접근 관리](/docs/ko/products/cloud/guides/security/cloud-access-management/index)를 참조하십시오.

<div id="related-resources">
  ## 관련 리소스
</div>

* [Apify Platform 문서](https://docs.apify.com)
* [Apify API 참조](https://docs.apify.com/api/v2)
* [Apify JavaScript client](https://docs.apify.com/api/client/js)
* [Apify Python client](https://docs.apify.com/api/client/python)
* [Apify Store (즉시 사용 가능한 Actor)](https://apify.com/store)
* [Apify 통합 개요](https://docs.apify.com/platform/integrations)
* [ClickHouse JavaScript client](/docs/ko/integrations/language-clients/js/index)