조회 테이블 API 2

지역

기본 URL은 프로젝트의 데이터 상주 위치에 따라 달라집니다. 이 페이지의 모든 예제에서 프로젝트가 Amplitude의 EU 데이터 센터를 사용하지 않는 한 기본 URL을 사용하십시오. 이 경우 이 표의 EU 기본 URL을 사용하십시오.

이 API는 data-api.amplitude.com(기본값) 또는 data-api.eu.amplitude.com(EU)를 사용합니다. 이벤트 수집은 api2.amplitude.com 또는 api.amplitude.com을(를) 사용합니다. 실험 관리는 experiment.amplitude.com을(를) 사용합니다. https://analytics.amplitude.com 호스트 이름은 이 API 엔드포인트가 아닌 분석 웹 앱(브라우저 UI)입니다.

데이터 상주	기본 URL
기본값	`https://data-api.amplitude.com`
EU	`https://data-api.eu.amplitude.com`

CSV 파일 요구 사항

CSV 파일은 다음 요구 사항을 준수해야 합니다.

최대 파일 크기는 100MB입니다. 파일의 행 수는 1,000,000개를 초과할 수 없습니다.
첫 번째 행에는 열 이름이나 헤더가 포함되어야 합니다.
첫 번째 열은 매핑 속성 값과 일치해야 하며 고유한 값을 포함해야 합니다. 조회 테이블은 정확히 일치하는 항목을 검색하며 대소문자를 구분합니다.
쉼표로 열을 구분하십시오.
줄바꿈을 사용하여 행을 구분합니다.
필드 값에 쉼표나 따옴표가 포함되어 있는 경우 값을 큰따옴표로 묶습니다. 첫 번째 큰따옴표는 열 데이터의 시작을 나타내며 마지막 큰따옴표는 열 데이터의 끝을 나타냅니다. 값에 큰따옴표가 있는 문자열이 포함되어 있는 경우 Amplitude는 해당 따옴표를 두 개의 큰따옴표 ""로 바꿉니다.

조회 테이블 작성

기존 속성을 생성할 새 속성에 매핑하는 CSV를 업로드하여 룩업 테이블 객체를 생성합니다. 요청을 multipart/form-data 콘텐츠 유형과 함께 전송합니다.

매개 변수

이름	설명
`name`	필수입니다. 유형: `string`. 테이블의 이름입니다.
`file`	필수입니다. 유형: `file`. 매핑의 CSV 표현입니다.
`key`	필수입니다. 유형: `string`. 조회 테이블의 키로 사용할 CSV 형식의 열입니다.
`property`	필수입니다. 유형: `JSON`. CSV의 키 열에 매핑할 Amplitude의 속성입니다.
`property.value`	필수입니다. 유형: `string`. Amplitude의 속성 이름입니다.
`property.type`	필수입니다. 유형: `string`. Amplitude의 속성 유형입니다.
`property.groupType`	선택 사항입니다. 유형: `string`. 속성이 그룹 속성인 경우에만 필요합니다.

요청 예제

curl

curl -L -X POST 'https://data-api.amplitude.com/api/3/lookup_table' \
        -u API_KEY:SECRET_KEY \
        -F 'file=@"/path/to/file.csv";type=text/csv' \
        -F 'name=":name"' \
        -F 'key=":key"' \
        -F 'property="{\"value\": \":propertyName\", \"type\": \":propertyType\", \"groupType\":  \":propertyGroupType\"}";type=application/json'

응답

json

{
  "appId": "<projectId>",
  "name": "example-lookup",
  "columnHeaders": ["Language"],
  "createdAt": 1715912516,
  "createdBy": "api",
  "lastModifiedAt": 1715912516,
  "lastModifiedBy": "api",
  "isDeleted": false,
  "isConfigured": true,
  "keyColumnHeader": "SKU",
  "keyProperty": {
    "type": "event",
    "value": "example",
    "groupType": "User"
  },
  "fileName": "lookup-table-example.csv",
  "rowCount": 3,
  "sizeBytes": 0
}

조회 테이블 검색

이름별로 조회 테이블을 검색합니다.

매개 변수

이름	설명
`name`	필수입니다. 유형: `string`. 테이블의 이름입니다.

요청 예제

curl -L -X GET 'https://data-api.amplitude.com/api/3/lookup_table/:name' \
        -u API_KEY:SECRET_KEY

응답

json

{
  "appId": "<projectId>",
  "name": "example-lookup",
  "columnHeaders": ["Language"],
  "createdAt": 1715912516,
  "createdBy": "api",
  "lastModifiedAt": 1715912516,
  "lastModifiedBy": "api",
  "isDeleted": false,
  "isConfigured": true,
  "keyColumnHeader": "SKU",
  "keyProperty": {
    "type": "event",
    "value": "example",
    "groupType": "User"
  },
  "fileName": "lookup-table-example.csv",
  "rowCount": 3,
  "sizeBytes": 5
}

CSV 다운로드

조회 테이블 객체를 CSV로 다운로드합니다. 전체 증분 변경 사항은 다운로드된 파일에 적용됩니다.

매개 변수

이름	설명
`name`	필수입니다. 유형: `string`. 테이블의 이름입니다.

요청 예제

curl -L -X GET 'https://data-api.amplitude.com/api/3/lookup_table/:name/csv' \
        -u API_KEY:SECRET_KEY

조회 테이블 재지정

이미 Amplitude에 업로드된 CSV를 대체하는 CSV를 업로드하여 조회 테이블 객체를 재정의합니다. 요청을 multipart/form-data 콘텐츠 유형과 함께 전송합니다.

매개 변수

이름	설명
`name`	필수입니다. 유형: `string`. 테이블의 이름입니다.
`file`	선택 사항입니다. 유형: `file`. 매핑의 CSV 표현입니다.
`property`	선택 사항입니다. 유형: `JSON`. CSV의 키 열에 매핑할 Amplitude의 속성입니다.
`property.value`	선택 사항입니다. 유형: `string`. Amplitude의 속성 이름입니다.
`property.type`	선택 사항입니다. 유형: `string`. Amplitude의 속성 유형입니다.
`property.groupType`	선택 사항입니다. 유형: `string`. 속성이 그룹 속성인 경우에만 필요합니다.

요청 예제

curl -L -X PUT 'https://data-api.amplitude.com/api/3/lookup_table/:name' \
        -u API_KEY:SECRET_KEY \
        -F 'file=@"/path/to/file.csv";type=text/csv' \
        -F 'property="{\"value\": \":propertyName\", \"type\": \":propertyType\", \"groupType\":  \":propertyGroupType\"}";type=application/json'

응답

json

{
  "appId": "<projectId>",
  "name": "example-lookup",
  "columnHeaders": ["Language"],
  "createdAt": 1715912516,
  "createdBy": "api",
  "lastModifiedAt": 1715912516,
  "lastModifiedBy": "api",
  "isDeleted": false,
  "isConfigured": true,
  "keyColumnHeader": "SKU",
  "keyProperty": {
    "type": "event",
    "value": "example",
    "groupType": "User"
  },
  "fileName": "lookup-table-example.csv",
  "rowCount": 3,
  "sizeBytes": 0
}

룩업 테이블 업데이트

조회 테이블의 열과 데이터를 업데이트합니다. CSV 파일을 제공하면 Amplitude는 해당 파일을 기존 CSV와 병합합니다. 이 기능은 전체 교체 대신 CSV의 증분 업데이트를 지원합니다.

매개 변수

이름	설명
`name`	유형: `string`. 테이블의 이름입니다.
`file`	유형: `file`. 매핑의 CSV 표현입니다.
`property`	유형: `JSON`. CSV의 키 열에 매핑할 Amplitude의 속성입니다.
`property.value`	유형: `string`. Amplitude의 속성 이름입니다.
`property.type`	유형: `string`. Amplitude의 속성 유형입니다.
`property.groupType`	유형: `string`. 속성이 그룹 속성인 경우에만 필요합니다.

요청 예제

curl -L -X PATCH 'https://data-api.amplitude.com/api/3/lookup_table/:name' \
        -u API_KEY:SECRET_KEY
        -F 'file=@"/path/to/file.csv";type=text/csv' \
        -F 'property="{\"value\": \":propertyName\", \"type\": \":propertyType\", \"groupType\":  \":propertyGroupType\"}";type=application/json'

응답

json

{
  "appId": "<projectId>",
  "name": "example-lookup",
  "columnHeaders": ["Language"],
  "createdAt": 1715912516,
  "createdBy": "api",
  "lastModifiedAt": 1715912516,
  "lastModifiedBy": "api",
  "isDeleted": false,
  "isConfigured": true,
  "keyColumnHeader": "SKU",
  "keyProperty": {
    "type": "event",
    "value": "example",
    "groupType": "User"
  },
  "fileName": "lookup-table-example.csv",
  "rowCount": 3,
  "sizeBytes": 0
}

조회 테이블 삭제

조회 테이블을 삭제합니다.

매개 변수

이름	설명
`name`	필수입니다. 유형: `string`. 테이블의 이름입니다.

요청 예제

curl -L -X DELETE 'https://data-api.amplitude.com/api/3/lookup_table/:name' \
        -u API_KEY:SECRET_KEY

응답

json

{
  "message": "Lookup table <:name> deleted successfully",
  "success": true
}

모든 조회 테이블 나열

프로젝트의 모든 룩업 테이블을 나열합니다.

요청 예제

curl -L -X GET 'https://data-api.amplitude.com/api/3/lookup_table' \
        -u API_KEY:SECRET_KEY

응답

json

[
  {
    "appId": "<projectId>",
    "name": "example-lookup",
    "columnHeaders": ["Language"],
    "createdAt": 1715912516,
    "createdBy": "api",
    "lastModifiedAt": 1715912516,
    "lastModifiedBy": "api",
    "isDeleted": false,
    "isConfigured": true,
    "keyColumnHeader": "SKU",
    "keyProperty": {
      "type": "event",
      "value": "example",
      "groupType": "User"
    },
    "fileName": "lookup-table-example.csv",
    "rowCount": 3,
    "sizeBytes": 5
  },
  {
    "appId": "<projectId>",
    "name": "example-lookup-2",
    "columnHeaders": ["Language"],
    "createdAt": 1715912516,
    "createdBy": "api",
    "lastModifiedAt": 1715912516,
    "lastModifiedBy": "api",
    "isDeleted": false,
    "isConfigured": true,
    "keyColumnHeader": "SKU",
    "keyProperty": {
      "type": "event",
      "value": "example",
      "groupType": "User"
    },
    "fileName": "lookup-table-example.csv",
    "rowCount": 50,
    "sizeBytes": 10
  }
]

오류 코드

모든 룩업 테이블 API는 이러한 공통 오류 코드를 공유합니다.

구조

이름	설명
`statusCode`	오류의 HTTP 상태 코드입니다. 400, 409, 413
`message`	사람이 읽을 수 있는 오류를 설명하는 메시지
`errorCode`	정적 오류 코드 문자열
`extraParams`	각 오류는 오류의 정확한 원인을 보다 잘 지적할 수 있도록 응답에 추가 매개 변수를 포함할 수 있습니다.

유형

코드	설명
`LOOKUP_TABLE_INVALID_FILE_COUNT`	단일 조회 테이블에 대해 둘 이상의 파일을 업로드하려고 시도했습니다.
`LOOKUP_TABLE_INVALID_FILE_SIZE`	100MB보다 큰 파일을 사용하여 조회 테이블을 생성/편집했습니다.
`LOOKUP_TABLE_INVALID_FILE_TYPE`	CSV가 아닌 파일을 사용하여 조회 테이블을 생성/편집했습니다.
`LOOKUP_TABLE_INVALID_KEY_COLUMN`	테이블 헤더에 없는 "키" 입력값을 사용하여 조회 테이블을 생성했습니다.
`LOOKUP_TABLE_INVALID_VALUE_COLUMN`	업로드된 파일의 셀 길이가 1,024자를 초과합니다.
`LOOKUP_TABLE_INVALID_KEY_PROPERTY`	제공된 키 속성이 Amplitude에 존재하지 않습니다.
`LOOKUP_TABLE_INVALID_NUMBER_OF_ROWS`	1백만 개 이상의 행을 가진 파일을 사용하여 조회 테이블을 생성/편집했습니다.
`LOOKUP_TABLE_KEY_COLUMN_DUPLICATE_VALUES`	지정된 키 열에 중복된 값이 있습니다.
`LOOKUP_TABLE_INVALID_TABLE_NAME`	제공된 이름이 잘못되었습니다.
`LOOKUP_TABLE_MALFORMED_CSV`	제공된 CSV가 올바르게 처리되지 않았습니다. 자세한 내용은 오류 메시지를 참조하십시오.
`LOOKUP_TABLE_INVALID_INPUT`	필드에 대한 입력이 예상과 일치하지 않습니다. 자세한 내용은 오류 메시지를 참조하십시오.
`LOOKUP_TABLE_ALREADY_EXISTS`	제공된 프로젝트에 이미 존재하는 테이블을 생성했습니다.
`LOOKUP_TABLE_DOES_NOT_EXIST`	존재하지 않는 테이블을 로드하거나 편집하려고 시도했습니다.
`LOOKUP_TABLE_INVALID_COLUMN_HEADERS`	파일의 열 헤더가 올바르게 처리되지 않았습니다.

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