Airtable 확장 프로그램으로 필드 매핑하기
GenderAPI 확장 프로그램은 선택한 필드에서 이름 또는 이메일 주소를 읽고, 추정된 성별 신호를 별도의 대상 필드에 기록합니다. 국가, probability, 찾은 이름(Found Name)도 매핑할 수 있으며, 성별 대상 필드에 이미 값이 있는 레코드는 건너뛸 수 있습니다.
2026년 9월 27일에 검토한 확장 프로그램 소스 코드는 이름과 이메일 주소용 기존 V1 엔드포인트와 최상위 수준의 응답 필드를 사용합니다. 이 가이드는 확장 프로그램에 내장된 워크플로를 설명합니다. 설치된 확장 프로그램은 이 가이드와 별개로 바뀔 수 있으므로, 아래 매핑을 적용하기 전에 사용할 수 있는 설정을 확인하세요.
베이스를 연결하고 필드 준비하기
- 사용할 Airtable 베이스를 열고 "Extensions"에서 GenderAPI.io를 추가한 뒤 확장 프로그램을 실행하세요. 확장 프로그램에 표시되는 연결 단계를 완료하세요.
- 이 작업에 사용할 크레딧 API 키를 선택하세요. 남은 잔액을 확인하고, 이 키가 의도한 GenderAPI 계정에 연결되어 있는지 확인하세요.
- 테이블과 이름 또는 이메일 주소가 들어 있는 원본 필드를 선택하세요. 원래 입력은 해당 필드에 그대로 두고, 결과용 필드는 따로 만드세요.
- 필수인 성별 대상 필드와 선택 사항인 보조 대상 필드를 고르세요. 서식이 적용된 백분율을 원하면 percent 필드를, 원래 probability 척도를 유지하려면 number 필드를 사용하세요.
- 이미 값이 채워진 성별 대상 필드를 유지할지 결정하세요. 건너뛰기를 켜면 이전 실행에서 남은 판정되지 않은 텍스트 값도 유지되므로, 의도적으로 다시 처리하려는 결과만 지우세요.
확장 프로그램의 입력과 출력 매핑하기
원본 필드에는 이름과 이메일 주소가 섞여 있어도 됩니다. 검토한 구현에서는 @ 기호가 포함된 값이 이메일 처리 경로로 전달됩니다. 이 분기 규칙은 메일함이 실제로 존재하는지 검증하지 않습니다.
| 확장 프로그램 설정 | 필수 | 값과 동작 |
|---|---|---|
| 크레딧 API 키 | 예 | 선택한 GenderAPI 계정 API 키가 처리된 조회에 필요한 크레딧을 제공합니다. |
| 테이블과 원본 필드 | 예 | 원본 셀에는 이름 또는 이메일 주소가 들어 있습니다. 비어 있는 원본 셀은 건너뜁니다. |
| 성별 대상 필드 | 예 | 확장 프로그램이 사용하는 API의 gender 필드 값을 받습니다. 판정되지 않은 값은 male, female과 구분해 두세요. |
| 국가 대상 필드 | 아니요 | 반환된 country 값을 받습니다. 요청에 적용되는 국가 필터가 아니라 출력 열입니다. |
| probability 대상 필드 | 아니요 | 기존 API의 probability 값을 받습니다. percent 필드에는 100으로 나눈 값이 들어가고, number 필드는 원래 척도를 유지합니다. |
| Found Name 대상 필드 | 아니요 | 확장 프로그램이 사용하는 API가 이름을 반환하면 그 이름을 받습니다. 이 추정된 후보는 원본 값과 구분해 두세요. |
| 값이 채워진 성별 필드 건너뛰기 | 아니요 | 판정되지 않은 텍스트를 포함해 대상 필드에 이미 값이 있는 레코드를 유지합니다. 실행할 때마다 이 설정이 선택되어 있는지 확인하세요. |
테이블 전체를 처리하기 전에 소규모로 실행해 보기
이름, 이메일 주소, 빈 셀, 모호한 입력이 들어 있는 작은 테스트 테이블로 시작하세요. 기본 테이블을 처리하기 전에 선택한 대상 필드와 Airtable이 probability 척도를 어떻게 표시하는지 확인하세요.
검토한 확장 프로그램 코드에서는 판정되지 않은 결과의 기본값이 텍스트 null과 probability 0으로 표시될 수 있습니다. 확장 프로그램이 사용하는 API의 일부 실패 응답도 이 기본값을 남길 수 있으며, 연결 오류가 발생하면 레코드가 변경되지 않은 채로 남을 수 있습니다. 실행 상태와 영향을 받은 행을 확인하세요. 텍스트 null만으로는 조회가 성공적으로 완료되었다고 볼 수 없습니다.
실행 후에는 기존 값을 확인하세요. 직접 성별을 지정하지 말고, 판정되지 않은 결과는 검토용으로 남겨 두세요. 이름 기반 추정은 그 사람의 성 정체성을 확인하지 않으며, 반환된 국가는 거주지를 증명하지 않습니다.
| 보이는 결과 | 조치 |
|---|---|
| 의도한 열에 예상한 결과가 있음 | 매핑을 나중에 검토할 수 있도록 원래 입력과 보조 필드를 유지하세요. |
| 텍스트 null 또는 probability 0 | 판정되지 않은 상태로 두고, 다시 조회할지 결정하기 전에 작업 상태를 확인하세요. |
| 이전에 값이 채워진 대상 필드가 변경되지 않음 | 건너뛰기 설정을 확인하세요. 의도적으로 값을 유지한 결과일 수 있습니다. |
| 키 또는 크레딧 관련 메시지, 또는 오류 후 결과가 변경되지 않음 | 계정 또는 연결 문제를 해결하고, 다시 시작하기 전에 영향을 받은 레코드를 파악하세요. |
선택한 크레딧과 재실행 관리하기
이 확장 프로그램은 선택한 GenderAPI 키로 값을 하나씩 조회합니다. 건너뛰지 않은 같은 레코드를 다시 실행하면 새 조회가 전송되어 크레딧이 다시 차감될 수 있습니다. Airtable 자체 요금제와 확장 프로그램 이용 가능 여부는 이 계정 잔액과 별개입니다.
확장 프로그램의 출력에는 V2의 data/meta 응답, 명시적인 AI 모드 선택, 항목별 usage 객체, V2 일괄 요청 규격이 포함되지 않습니다. 이 워크플로에는 기존 V1 참조를 사용하고, 이러한 제어 기능이 필요하면 아래의 별도 API 선택지를 사용하세요.
확장 프로그램은 매핑된 값을 처리용으로 전송하고 결과를 베이스에 다시 기록합니다. 처리할 레코드에 대해 공개된 개인정보 처리방침과 확장 프로그램 권한을 검토하고, 관련 없는 필드는 원본 매핑에 포함하지 마세요.
구조화된 응답이 필요하면 V2 사용하기
직접 구축하는 연동에서는 GenderAPI V2가 이름, 이메일 주소, 사용자 이름을 받아 결과, 신뢰도, 출처, 사용량을 나타내는 명시적인 필드를 반환합니다. 이 연결은 별도로 설정하세요. V2 가이드를 읽는다고 해서 설치된 앱이나 앱이 기록하는 출력 열이 바뀌지는 않습니다.
Python과 Node.js 예시는 단일 요청, 일괄 요청, 알 수 없는 결과, 운영상 오류를 다룹니다. 인증 가이드부터 시작하고, 과금 대상 요청을 보내기 전에 AI 모드를 선택하세요.
자주 묻는 질문
Airtable 확장 프로그램은 GenderAPI V2를 사용하나요?
2026년 9월 27일에 검토한 확장 프로그램 소스 코드는 이름과 이메일 주소용 기존 V1 엔드포인트를 사용합니다. 별도로 구축하는 V2 연결은 요청 필드와 응답 필드가 다르며, 설치된 확장 프로그램을 업그레이드하지 않습니다.
하나의 원본 필드에 이름과 이메일 주소를 함께 넣을 수 있나요?
예. 검토한 확장 프로그램은 @ 기호가 포함된 비어 있지 않은 값을 이메일 조회로, 그 밖의 값을 이름 조회로 보냅니다. 이는 입력 분기일 뿐 메일함 검증이 아닙니다.
percent 필드에서는 왜 probability가 다르게 보이나요?
확장 프로그램은 Airtable이 백분율 서식으로 표시할 수 있도록 Airtable percent 필드에 대해 기존 API의 probability 값을 100으로 나눕니다. number 유형의 대상 필드는 원래 척도를 유지합니다. 이는 V2의 confidence 필드가 아닙니다.
건너뛰기 옵션을 켜면 판정되지 않은 결과도 유지되나요?
예, 대상 필드에 이미 값이 있으면 유지됩니다. 이전 실행에서 남은 텍스트 null도 여기에 포함됩니다. 해당 레코드를 검토하고, 의도적으로 다시 처리하려는 값만 지우세요.
출처와 문서
이 가이드는 에 마지막으로 검토했습니다. 설치 방법은 각 플랫폼의 문서에서 확인하고, 별도의 V2 연동을 만들 때는 아래 API 문서를 사용하세요.