Airtable API 레코드 조회

테이블에 저장된 레코드들을 한 번에 읽어올 때 쓰는 게 Airtable 레코드 조회(List records) API예요. GET /v0/{baseId}/{tableIdOrName} 요청 하나로 테이블 전체를 읽을 수 있고, 쿼리 파라미터를 조합하면 원하는 레코드만 필터링하거나 정렬해서 가져올 수 있어요. 이 글에서는 레코드 조회의 기본 사용법과 페이지네이션, 필터·정렬 쿼리 파라미터를 하나씩 살펴볼게요.

출처: 문서

본문

기본 사용법

레코드를 조회하는 기본 엔드포인트는 다음과 같아요.

GET https://api.airtable.com/v0/{baseId}/{tableIdOrName}

여기서 baseId는 베이스 ID, tableIdOrName은 테이블 ID 또는 테이블 이름이에요. Airtable은 테이블 이름과 테이블 ID를 서로 바꿔 쓸 수 있게 해주는데요, 테이블 이름이 바뀌어도 API 요청을 수정할 필요가 없도록 테이블 ID를 쓰는 걸 권장해요. 인증은 Authorization: Bearer YOUR_TOKEN 헤더에 개인 액세스 토큰(Personal access token)을 넣어서 해요.

curl "https://api.airtable.com/v0/{baseId}/{tableIdOrName}" \
-H "Authorization: Bearer YOUR_TOKEN"

응답은 다음과 같은 형태로 돌아와요.

{
  "records": [
    {
      "createdTime": "2022-09-12T21:03:48.000Z",
      "fields": {
        "Address": "333 Post St",
        "Name": "Union Square",
        "Visited": true
      },
      "id": "rec560UJdUtocSouk"
    },
    {
      "createdTime": "2022-09-12T21:03:48.000Z",
      "fields": {
        "Address": "1 Ferry Building",
        "Name": "Ferry Building"
      },
      "id": "rec3lbPRG4aVqkeOQ"
    }
  ]
}

각 레코드는 레코드 ID(id), 생성 시각(createdTime), 그리고 필드 값(fields)으로 이루어져 있어요. fields는 기본적으로 필드 이름을 키로 쓰는데, returnFieldsByFieldId 파라미터를 true로 주면 필드 ID를 키로 반환받을 수 있어요. 참고로 응답에는 값이 비어 있는 필드(예: "", [], false)는 포함되지 않아요.

페이지네이션(offset)

서버는 레코드를 한 번에 한 페이지씩 반환해요. 각 페이지에는 pageSize개(기본 100개)의 레코드가 들어 있고요. 아직 처리할 레코드가 더 남아 있으면 응답에 offset 값이 함께 오는데, 이 값을 다음 요청의 offset 파라미터에 그대로 넣어서 다음 페이지를 가져와요. 페이지네이션을 반복하다가 테이블의 끝에 도달하면 멈춰요. maxRecords 파라미터를 전달하면 그 개수에 도달했을 때도 멈추게 할 수 있어요.

정리하면, record 조회는 다음 쿼리 파라미터를 지원해요.

pageSize — 요청 한 번에 반환할 레코드 수. 100 이하의 숫자여야 하고 기본값은 100이에요.
maxRecords — 요청 전체에서 반환할 레코드의 최대 총합. pageSize(기본 100)보다 크면 여러 페이지를 로드해야 할 수 있어요.
offset — 이전 요청에서 받은 값을 넣어 다음 페이지를 가져와요.

필터·정렬

쿼리 파라미터로 결과를 필터링·정렬·포맷할 수 있는데, 이 파라미터들은 URL 인코딩이 필요해요. Airtable이 제공하는 API URL 인코더 도구를 쓰면 편하고, Airtable.js 같은 헬퍼 라이브러리를 쓰면 자동으로 인코딩돼요.

filterByFormula — 레코드를 거를 공식(formula)을 지정해요. 공식은 레코드마다 평가되고, 그 결과가 0·false·""·NaN·[]·#Error!가 아니면 해당 레코드가 응답에 포함돼요. view 파라미터와 함께 쓰면 그 뷰에 있는 레코드 중 공식을 만족하는 것만 돌려줘요. 공식은 필드 이름이나 필드 ID를 쓸 수 있어요.
sort — 레코드의 정렬 순서를 정하는 정렬 객체들의 배열이에요. 각 객체는 정렬할 필드 이름인 field 키를 반드시 가져야 하고, 정렬 방향인 direction 키는 선택적으로 "asc" 또는 "desc"를 줄 수 있어요. 기본 방향은 "asc"예요.
view — 테이블의 뷰 이름이나 ID를 지정해요. 설정하면 그 뷰에 있는 레코드만 반환되고, 뷰의 정렬 순서대로 정렬돼요. 단 sort 파라미터가 있으면 그게 뷰의 정렬을 덮어써요. sort도 view도 없으면 레코드의 순서는 임의예요.
fields — 결과에 포함할 필드 이름(또는 ID) 목록. 모든 필드가 필요 없을 때 이 파라미터로 전송 데이터 양을 줄일 수 있어요.
cellFormat — 셀 값의 포맷. "json"(기본)은 필드 유형에 따라 JSON으로, "string"은 필드 유형과 무관하게 사용자에게 보이는 문자열로 포맷해요. "string"을 쓰려면 timeZone과 userLocale 파라미터가 필수예요.
timeZone / userLocale — cellFormat을 "string"으로 쓸 때 날짜를 포맷하는 데 사용할 시간대와 로케일이에요.
returnFieldsByFieldId — true로 주면 필드 객체의 키를 필드 이름 대신 필드 ID로 반환해요. 기본값은 false예요.
recordMetadata — "commentCount"를 지정하면 각 레코드에 댓글 수(commentCount)를 포함해줘요.
includeDateDependencyMetadata — true로 주면 연결 레코드(linked record) 셀 값을 레코드 ID 대신 객체로 반환해요.

필드(fields) 파라미터로 필요한 것만 가져오기

테이블에 필드가 많고 필요하지 않은 필드가 있다면 fields로 필요한 필드만 골라서 데이터 전송량을 줄일 수 있어요.

curl "https://api.airtable.com/v0/{baseId}/{tableIdOrName}?fields%5B%5D=Name&fields%5B%5D=Address" \
-H "Authorization: Bearer YOUR_TOKEN"

위 예시처럼 필드 이름을 URL 인코딩된 형태(fields[]=)로 여러 번 넣어주면 그 필드만 응답에 포함돼요.

주의할 점 (URL 길이 제한)

Airtable API는 16,000자보다 짧은 URL만 받아줘요. 인코딩된 공식(formula) 때문에 요청이 이 한도를 넘는 경우가 생길 수 있는데, 이때는 쿼리 파라미터 대신 요청 본문(body)에 파라미터를 넣어 POST /v0/{baseId}/{tableIdOrName}/listRecords로 요청하는 방법으로 해결할 수 있어요.

오류 응답

레코드 조회 과정에서 반복(iteration)이 시간 초과되면 다음과 같은 오류가 반환될 수 있어요. 클라이언트의 비활동이나 서버 재시작 때문에 발생할 수 있고, 이 경우 처음부터 반복을 다시 시작할 수 있어요.

{
  "error": {
    "type": "LIST_RECORDS_ITERATOR_NOT_AVAILABLE"
  }
}

더 알아보기 (Learn more)

공식 문서