개발자 API

Amplitude Developer API는 프로젝트, 택소노미, 기능 플래그, 분석, 대상 및 구현 스킬을 위한 OpenAPI에서 정의한 REST API입니다. amp CLI의 기반이 되는 계약입니다.

기본 URL

인증

대부분의 Developer API 요청에는 HTTP Bearer 토큰이 필요합니다. Authorization 헤더에 전송하십시오:

bash
Authorization: Bearer YOUR_ACCESS_TOKEN

Bearer 토큰은 디바이스 흐름의 OAuth 액세스 토큰 또는 개인 액세스 토큰(PAT)입니다. 둘 다 동일한 헤더와 범위 모델을 사용하며, 어느 쪽이든 해당 범위가 허용하는 엔드포인트를 호출할 수 있습니다. 장치 인증, 토큰 교환 및 스킬 엔드포인트에는 Bearer 토큰이 필요 없습니다.

Get authenticated context를 호출하여 토큰이 어떤 자격 증명 유형, 범위 및 조직으로 확인되는지 조회합니다.principal.auth_type 필드는 oauth, pat, service_account 또는 api_key을(를) 반환합니다.

OAuth 디바이스 플로우

디바이스 플로우를 사용하여 클라이언트 시크릿을 포함하지 않고 CLI, 스크립트 또는 기타 입력 기능이 제한된 클라이언트를 인증합니다. 이 흐름은 두 단계로 구성됩니다. 즉, 장치 인증 요청을 시작한 다음 토큰을 폴링합니다.

  1. 장치 인증 요청을 시작합니다. 필요한 공백으로 구분된 scope을(를) device-authorization 엔드포인트로 전송합니다. 이 엔드포인트에는 Bearer 토큰이 필요하지 않습니다.

    bash
    curl -X POST https://developer-api.amplitude.com/v1/auth/device-authorization \
      -H "Content-Type: application/json" \
      -d '{
        "scope": "projects:read analytics:read"
      }'
    

    응답에는 device_code, user_code, verification_uri (및 verification_uri_complete), expires_in, 폴링 interval가 포함됩니다.

  2. 사용자에게 요청을 승인하도록 지시합니다. user_code을(를) 표시하고 사용자를 verification_uri(으)로 보내거나 verification_uri_complete 을(를) 직접 열어 브라우저에서 요청을 승인하도록 합니다.

  3. 토큰에 대해 폴링합니다. 사용자가 요청을 승인하는 동안 device_code grant를 사용하여 토큰 엔드포인트를 폴링하십시오:

    bash
    curl -X POST https://developer-api.amplitude.com/v1/auth/token \
      -H "Content-Type: application/json" \
      -d '{
        "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
        "device_code": "YOUR_DEVICE_CODE"
      }'
    

    1단계의 interval보다 자주 폴링하지 마십시오. 사용자가 요청을 승인하면 토큰 엔드포인트는 access_token, token_type, expires_in, refresh_token, scope 및 id_token을(를) 반환합니다. 후속 요청 시 Bearer 토큰으로 access_token을(를) 전송하십시오.

개인 액세스 토큰

개인 액세스 토큰(PAT)은 CI 파이프라인 및 디바이스 흐름을 실행하는 것이 현실적이지 않은 기타 비대화형 환경에서 장기간 지속되는 Bearer 자격 증명입니다. OAuth 액세스 토큰과 동일한 방식으로 Authorization헤더에 PAT를 전송합니다. amp CLI는 기존 PAT를 amp auth login의 대체로 비대화형으로 허용합니다(예: amp auth pat --with-token).

범위

연동에 필요한 범위만 요청하십시오. 장치 인증 요청의 scope 필드는 공백으로 구분된 목록을 사용하며, PAT는 자체적으로 고정된 범위 집합을 갖습니다. GET /v1/context은(는) principal.scopes에(게) 활성 토큰의 부여된 범위를 보고합니다.

토큰에 필수 범위가 없는 요청은 403오류를 반환합니다. 공유 오류 형식에 대해서는 규칙을 참조하십시오.

규칙

페이징

목록 엔드포인트는 cursor 쿼리 매개변수와 이전 응답의 pagination.next_cursor에서 가져온 불투명 값인 limit 쿼리 매개변수(기본값 50, 최대 200)를 허용합니다. 각 목록 응답에는 pagination 객체가 포함되어 있습니다.

json
{
  "pagination": {
    "next_cursor": "eyJvZmZzZXQiOjUwfQ",
    "has_more": true
  }
}

next_cursor은(는) 마지막 페이지에 있는 null입니다. 기본 검색 인덱스는 쿼리당 결과를 10,000으로 제한합니다. 잘 구성된 페이지네이션은 해당 한도 전에 중지됩니다. 커서가 이를 초과하는 요청은 400 오류 및 error_code: pagination_not_supported와(과) 함께 반환됩니다.

오류

오류 응답은 RFC 9457 문제 세부 정보를 사용하며 다음과 같이 제공됩니다application/problem+json:

json
{
  "type": "https://developer-api.amplitude.com/errors/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "limit must be less than or equal to 200",
  "instance": "/v1/projects/abc123/charts",
  "error_code": "validation_error",
  "retryable": false,
  "retry_after_seconds": null,
  "validation_errors": null
}

retryable은(는) 동일한 요청을 재시도할 수 있는지 여부를 알려줍니다. retryable이(가) true인 경우, retry_after_seconds은(는) 백오프를 제안할 수 있습니다. 요청 유효성 검사 실패로 인해 validation_errors이(가) 채워집니다.

Idempotency

Idempotency-Key을(를) 허용하는 요청에는 8~255자 사이의 고유 문자열이 필요합니다. 동일한 키를 다시 사용하여 중복된 변이 발생할 위험 없이 요청을 안전하게 재시도하십시오. 각 엔드포인트의 매개변수를 확인하여 이 헤더를 허용할지 여부를 확인합니다.

모의 실행

삭제 및 아카이브 작업은 dry_run 쿼리 매개변수(기본 false)를 사용합니다. 변경 사항을 적용하지 않고 라이브 작업과 동일한 검사를 수행하여 요청을 유효성 검사하려면 dry_run=true을(를) 설정하세요.

이 내용이 도움이 되었나요?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

이 페이지에서