채널 분류기 API

인증

이 API는 프로젝트의 API 키와 비밀 키를 사용하여 기본 인증을 사용합니다. 요청 헤더에 base64로 인코딩된 자격 증명을 전달합니다. {api-key}:{secret-key}는 사용자 이름으로, api-key는 비밀번호로 대체합니다secret-key.

인증 헤더는 다음과 같은 형태여야 합니다.

--header 'Authorization: Basic YWhhbWwsdG9uQGFwaWdlZS5jb206bClwYXNzdzByZAo'

자세한 내용은 API 자격 증명 찾기로 이동하세요.

키/비밀 키 쌍은 API 호출의 범위를 단일 프로젝트로 지정하므로 프로젝트 A의 키를 사용한 호출은 프로젝트 B의 분류기를 읽거나 쓸 수 없습니다.

엔드포인트

요청은 https://amplitude.com(기본값) 또는 https://analytics.eu.amplitude.com (EU)를 사용합니다. https://analytics.amplitude.com호스트 이름은 분석 웹 앱(브라우저 UI)입니다. REST 요청에는 analytics.amplitude.com이 표에 나와 있는 호스트를 사용하십시오.

분류자 목록

인증된 프로젝트의 모든 채널 분류자를 반환합니다.

GET https://amplitude.com/api/2/channel-classifiers

curl --location --request GET 'https://amplitude.com/api/2/channel-classifiers' \
-u '{api-key}:{secret-key}'

응답

{
  "channelClassifiers": [
    {
      "id": "368",
      "name": "utm_channels",
      "displayName": "UTM Channels",
      "description": "Standard channel attribution",
      "csvText": "Channel,utm_source,utm_medium\nPaid Search,google|bing,cpc|paid\nDirect,ANY,direct",
      "csvDefinition": {
        "csvText": "Channel,utm_source,utm_medium\nPaid Search,google|bing,cpc|paid\nDirect,ANY,direct",
        "operatorsMap": { "utm_source": "IS", "utm_medium": "IS" },
        "columnMetadata": { "utm_source": "event_property", "utm_medium": "event_property" },
        "columnMetadataGroupType": {},
        "anyKeyword": "ANY",
        "separator": "|",
        "propertyMetadata": {},
        "useWaterfallLogic": true
      },
      "lastModified": "2026-05-10T18:09:22.275499"
    }
  ]
}

오류 응답

• 401 - 헤더가 누락되었거나 잘못된Authorization 형식입니다.
• 403 - 잘못된 API 키 또는 암호입니다.

이름으로 분류기 가져오기

단일 분류기에 대한 전체 정의를 해당 name로 반환합니다.

GET https://amplitude.com/api/2/channel-classifiers/{name}

curl --location --request GET 'https://amplitude.com/api/2/channel-classifiers/utm_channels' \
-u '{api-key}:{secret-key}'

경로 매개변수

응답

{
  "id": "368",
  "name": "utm_channels",
  "displayName": "UTM Channels",
  "description": "Standard channel attribution",
  "csvText": "Channel,utm_source,utm_medium\nPaid Search,google|bing,cpc|paid\nDirect,ANY,direct",
  "csvDefinition": {
    "csvText": "Channel,utm_source,utm_medium\nPaid Search,google|bing,cpc|paid\nDirect,ANY,direct",
    "operatorsMap": { "utm_source": "IS", "utm_medium": "IS" },
    "columnMetadata": { "utm_source": "event_property", "utm_medium": "event_property" },
    "columnMetadataGroupType": {},
    "anyKeyword": "ANY",
    "separator": "|",
    "propertyMetadata": {},
    "useWaterfallLogic": true
  },
  "lastModified": "2026-05-10T18:09:22.275499"
}

오류 응답

• 401 - 헤더가 누락되었거나 잘못된Authorization 형식입니다.
• 403 - 잘못된 API 키 또는 암호입니다.
• 404 - 이 프로젝트에서 해당 이름을 가진 분류자를 찾을 수 없습니다.

분류자 만들기

사용자가 제공한 name의 아래에 새 분류자를 생성합니다. 해당 이름을 가진 분류자가 프로젝트에 이미 있으면 409에서 실패합니다.

POST https://amplitude.com/api/2/channel-classifiers/{name}

curl --location --request POST 'https://amplitude.com/api/2/channel-classifiers/utm_channels' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "displayName": "UTM Channels",
  "description": "Standard paid/organic/social/email/direct/referral",
  "csvDefinition": {
    "csvText": "Channel,utm_source,utm_medium\nPaid Search,google|bing,cpc|paid\nOrganic Search,google|bing,organic\nEmail,ANY,email\nDirect,ANY,direct",
    "operatorsMap": {"utm_source": "IS", "utm_medium": "IS"},
    "columnMetadata": {"utm_source": "event_property", "utm_medium": "event_property"},
    "anyKeyword": "ANY",
    "separator": "|",
    "propertyMetadata": {},
    "useWaterfallLogic": true
  }
}'

경로 매개변수

바디 매개변수

응답

{
  "status": "created",
  "name": "utm_channels"
}

오류 응답

• 400 - 본문이 누락되었거나csvDefinition, 누락되었거나csvDefinition.csvText 또는 displayName1000자를 초과합니다.description
• 401 - 헤더가 누락되었거나 잘못된Authorization 형식입니다.
• 403 - 잘못된 API 키 또는 암호입니다.
• 409 - 이 프로젝트에 해당 이름을 가진 분류자가 이미 존재합니다.
• 413 - csvDefinition.csvText1MB보다 큽니다.

분류자 업데이트

기존 분류자의 정의를 요청 본문의 csvDefinition전체 정의로 바꿉니다. Amplitude는 부분적인 CSV 업데이트를 지원하지 않으며, displayName 및 description를 제공하는 경우에만 업데이트합니다.

PATCH https://amplitude.com/api/2/channel-classifiers/{name}

curl --location --request PATCH 'https://amplitude.com/api/2/channel-classifiers/utm_channels' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "csvDefinition": {
    "csvText": "Channel,utm_source,utm_medium\nPaid Search,google|bing|duckduckgo,cpc|paid\nDirect,ANY,direct",
    "operatorsMap": {"utm_source": "IS", "utm_medium": "IS"},
    "columnMetadata": {"utm_source": "event_property", "utm_medium": "event_property"},
    "anyKeyword": "ANY",
    "separator": "|",
    "propertyMetadata": {},
    "useWaterfallLogic": true
  }
}'

경로 매개변수

바디 매개변수

응답

{
  "status": "updated",
  "name": "utm_channels"
}

오류 응답

• 400 - 본문이 누락되었거나csvDefinition, 누락되었거나csvDefinition.csvText 또는 displayName1000자를 초과합니다.description
• 401 - 헤더가 누락되었거나 잘못된Authorization 형식입니다.
• 403 - 잘못된 API 키 또는 암호입니다.
• 404 - 해당 이름을 가진 분류자를 찾을 수 없습니다.
• 413 - csvDefinition.csvText1MB보다 큽니다.

csvDefinition 필드

csvDefinition 객체는 분류자 규칙을 정의합니다. 이 모양은 POST및 PATCH에서 동일합니다.

| 매개 변수 | 설명 | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- | | csvText | 필수입니다. 문자열(최대 1MB). UI가 생성한 그대로의 원시 CSV입니다. 첫 번째 열에는 결과 채널 이름이 포함되며 이후의 열에는 속성 규칙이 포함됩니다. 다중 값 일치를 위해 셀이 분할됩니다separator. anyKeyword(기본값)ANY을 사용하여 "전체 값과 일치"를 의미합니다. useWaterfallLogic가 true인 경우 Amplitude는 행을 위에서 아래로 순차적으로 평가합니다. | | operatorsMap | 선택 사항입니다. 객체입니다. 각 속성 열 이름을 비교 연산자(예: {"utm_medium": "IS"})에 매핑합니다. 생략된 경우 기본값은 정확한 일치(IS)입니다. | | columnMetadata | 선택 사항입니다. 객체입니다. 각 속성 열 이름을 해당 속성 유형(event_property, 또는 user_property)에 매핑합니다group_property. | | columnMetadataGroupType | 선택 사항입니다. 객체입니다. 각 속성 열 이름을 그룹 유형에 매핑합니다(해당 열이 그룹 속성을 참조하는 경우). | | anyKeyword | 선택 사항입니다. 문자열입니다. 셀 내부의 "전체 값과 일치"를 의미하는 키워드입니다. 기본값은 ANY입니다. | | separator | 선택 사항입니다. 문자열입니다. 여러 값의 셀을 구분하는 문자열입니다(예: "google 또는 bing"으로 |표현할google | bing 경우). 실제 속성 값 내에 나타나지 않는 항목을 선택하십시오. | | propertyMetadata | 선택 사항입니다. 객체입니다. 고급옵션 Amplitude가 operatorsMap+ columnMetadata에서 파생했을 데이터를 속성별로 재정의하는 사전 구축된 메타데이터입니다. 대부분의 발신자는 이를 {}로 남겨두고 Amplitude가 생성하도록 합니다. | | useWaterfallLogic | 선택 사항입니다. 부울입니다. true인 경우 Amplitude는 행을 위쪽에서 아래쪽으로 평가하고 첫 번째로 일치하는 행이 우선합니다. false인 경우, Amplitude는 각 행을 독립적으로 평가합니다. 기본값은 false입니다. |

일반적인 패턴

하나의 정의를 N 개의 프로젝트에 브로드캐스팅

이 API의 일반적인 사용 사례는 하나의 정규 CSV를 여러 개의 관련 Amplitude 프로젝트에 적용하는 것입니다(예: 국가당 하나의 프로젝트). 도구에 CSV를 넣은 다음 각 프로젝트의 (api-key, secret-key) 쌍을 반복하여 PATCH요청을 전송합니다. (또는 아직 분류자가 없는 프로젝트의 경우 POST)를 전송하십시오.

API에는 내장된 벌크 엔드포인트가 없습니다. 도구에서 프로젝트를 반복하십시오.

기여 분석을 위해 워터폴 논리 사용

순서가 중요한 경우(예를 들어 유료 검색을 캡처하는 행이 다른 방식으로도 일치할 수 있는 일반 이메일 행보다 우선해야 함) true 항목을 useWaterfallLogic(으)로 설정하십시오. 그런 다음 Amplitude는 행을 위에서 아래로 평가하고 첫 번째로 일치하는 항목이 적용됩니다. 각 행을 독립적으로 평가하려면 false이를 그대로 두십시오.

다중 값 셀

"여러 값 중 하나"를 표현하려면 사용자가 구성한 | 를 사용하십시오(예: separator):

Paid Search,google|bing|duckduckgo,cpc|paid

속성 값이 google|bing|duckduckgo인 경우 해당 세 값 중 하나와 일치하면 조건이 충족됩니다.