Make를 GenderAPI.io V2에 연결하기

계정과 원본 레코드 준비하기

이 예시는 이메일 주소를 기준으로 Shopify 레코드를 보강합니다. 원본 앱과 대상 앱에 대한 접근 권한, GenderAPI.io 계정 API 키, HTTP 액션에 필요한 플랫폼 기능이 필요합니다. 이 가이드에는 실제로 작동하는 로그인 정보나 연결된 계정이 들어 있지 않습니다.

V1과 V2는 같은 계정 API 키와 같은 잔액을 사용합니다. 과금되는 요청을 설정하기 전에 GET /api/v2/usage로 키를 확인하고, 이 엔드포인트의 응답에서 meta.access.mode 값이 api_key인지 확인하세요. 키가 없거나 인식되지 않으면 공유 IP 체험으로 대체될 수 있습니다. 운영 중인 자동화가 이를 모르는 채로 IP 체험에 의존해서는 안 됩니다.

설정하는 동안에는 워크플로를 비활성화해 두세요. 테스트 추정 요청에도 일반 크레딧이 차감됩니다. 이 가이드는 공개 문서와 V2 규격을 기준으로 검토했습니다. 이번 게시를 위해 어떤 플랫폼에서도 인증된 워크플로를 처음부터 끝까지 실행하지는 않았습니다.

• 인증과 무료 사용량 확인 →

Make에서 GenderAPI.io V2 요청 설정하기

• 시나리오에 맞는 Shopify 고객 트리거를 선택하고 대표성 있는 테스트 레코드를 불러오세요. 마지막 업데이트까지 고객 ID를 유지하고, 이메일이 비어 있는 레코드는 건너뛰세요.
• HTTP > Make a request를 추가하세요. 현재 HTTP 앱에서 API key 인증을 선택하고, 키 값 Bearer YOUR_API_KEY, 위치 Header, 매개변수 이름 Authorization으로 자격 증명을 만드세요. 키를 URL에 넣지 말고 자격 증명 저장소를 사용하세요.
• 메서드를 POST로, URL을 아래에 표시된 값으로 설정하세요. 요청 본문에는 application/json을 선택하고, 문자열 필드 type과 value, 그리고 문자열 필드 ai_mode를 담은 options 컬렉션으로 이루어진 데이터 구조를 선택하세요. type은 email로, ai_mode는 off로 설정하고 고객 이메일을 value에 매핑하세요.
• Parse response를 켜세요. Make의 데이터 구조로 만든 본문은 매핑된 값을 JSON으로 직렬화하므로, 따옴표가 들어간 이름이나 주소도 문자열을 직접 이어 붙일 필요가 없습니다.

보내기 전에 JSON 본문 확인하기

이 예시는 고정된 입력을 보여 줄 뿐이며, 예상 결과가 아닙니다. 먼저 요청 구조를 확인한 다음, 올바른 JSON 직렬화를 사용해 value를 매핑한 원본 필드로 바꾸세요. 플랫폼의 매핑 표현식을 문자 그대로의 텍스트로 API에 붙여 넣지 마세요.

다른 입력을 보낼 때는 type을 name, email 또는 username으로 설정하고 value에 해당 값을 지정하세요. country는 신뢰할 수 있는 국가 컨텍스트가 있을 때만 추가하세요. 이 필드는 선택 사항이며, 사람이 어느 나라에 거주하는지 조회하는 데 쓰이지 않습니다.

{
  "type": "email",
  "value": "alex@example.com",
  "options": {
    "ai_mode": "off"
  }
}

• 요청의 모든 필드, 유형, 기본값 →

업데이트를 켜기 전에 HTTP 단계 확인하기

이 고정된 HTTPS API 대상에는 리디렉션을 비활성화한 상태로 두세요. Make HTTP 앱의 버전을 바꾸는 경우, 설정 항목이 다를 수 있으므로 인증과 본문 설정을 다시 검토하세요.

의도적으로 테스트를 한 번 실행하고, 파싱된 응답 번들(bundle)을 확인한 다음, 고객 업데이트를 추가하기 전에 수용한 identified 결과, 알 수 없는 결과, 운영상의 실패를 위한 경로(route)를 각각 만드세요.

• Make HTTP 앱 설정 →
• Make의 API key 자격 증명과 헤더 위치 →
• Make의 미완료 실행 자동 재시도 →

identified 결과, 알 수 없는 결과, 실패를 따로 처리하기

대상 시스템의 업데이트를 선택하기 전에 응답 본문을 파싱하세요. 아래 JSON 경로는 V2 응답 본문을 기준으로 합니다. 플랫폼에 따라 본문을 감싸거나 평탄화할 수 있습니다. 의도적으로 실행한 테스트로 실제 반환 구조를 확인하고, 결과를 원본 레코드 ID와 연결해 두세요.

추정 결과는 사람의 정체성이나 본인이 밝힌 성별을 확정하지 않습니다. 본인이 제공한 정보와 분리해 저장하세요. 수용 기준은 자신의 사용 사례를 대표하는 데이터에 근거해 정하고, 데이터셋의 신뢰도와 AI의 신뢰도는 따로 평가하세요.

• V2 응답 전체 참조 →
• 오류, 시간 초과, 재시도 판단 →

Shopify에서는 해당 레코드만 업데이트하기

파싱된 HTTP 응답에서 아래 V2 본문 경로를 매핑하세요. Make는 본문을 모듈 출력 레이블 아래에 둘 수 있으므로, 확인한 번들에서 중첩된 data 및 meta 객체를 선택하세요. 트리거가 저장한 고객 ID에 해당하는 고객만 업데이트하고, 추정 데이터용 별도 필드나 정해 둔 태그 정책을 사용하세요.

업데이트를 켜기 전에 identified 결과, 알 수 없는 결과, 오류 분기를 각각 테스트하세요. 가상의 샘플 응답을 사용하면 새 추정 요청을 보내지 않고도 분기 조건을 확인할 수 있습니다. 대상 앱의 업데이트는 위의 확인 결과에 따라야 하며, 관련 없는 필드나 태그를 덮어쓰면 안 됩니다.

• 응답 필드와 알 수 없는 결과 →
• 정확도와 신뢰도 설명 →
• 데이터 출처와 날짜가 명시된 데이터셋 개요 →

재시도와 중복 차감 관리하기

Make의 오류 처리기(error handler)와 미완료 실행(incomplete execution) 설정을 검토하세요. 일부 일시적인 오류는 명시적인 Retry 처리기가 없어도 재시도될 수 있습니다. HTTP 모듈을 재시도하면 과금되는 요청이 새로 전송될 수 있습니다. 요청은 성공했지만 이후 Shopify 업데이트가 실패했다면, 그 업데이트를 복구할 때 저장해 둔 요청 출력을 다시 사용하세요.

GenderAPI로 보내는 새 요청은 각각 독립된 작업입니다. 전송하기 전에 저장해 둔 원본 ID와 처리 상태를 사용해 워크플로에서 반복된 원본 이벤트의 중복을 제거하세요. 원본 레코드 ID는 서버 측에서 반복 요청을 막아 주는 키가 아닙니다.

성공한 알 수 없는 결과는 차감이 완료된 결과입니다. 시간 초과가 발생하거나 응답이 불완전하면 결과와 차감 여부를 모두 알 수 없을 수 있습니다. 요청 참조값이 있으면 보관하고, 요청을 다시 보내기 전에 차감 내역을 확인하세요. 요청 한도 응답에 Retry-After 헤더가 있으면 그 값을 따르세요.

• 크레딧과 과금 상태 →

AI를 사용할 시점 선택하기

forceToGenderize는 이름, 이메일 주소, 사용자 이름에 선택적으로 사용할 수 있습니다. 이 옵션을 켜면 ai_mode를 생략하거나 fallback을 사용하세요. off와 always는 함께 쓸 수 없으며 422를 반환합니다. 최종 차감으로 잔액이 0 아래로 내려가더라도 시작 잔액이 0보다 크면 요청을 시작할 수 있습니다.

별명 모드는 name: null과 함께 성별을 반환할 수 있으며, 알 수 없는 결과를 반환할 수도 있습니다. 일반 AI 폴백도 별명 추정도 정확하거나 null이 아닌 답을 보장하지 않습니다.

• AI 옵션과 별명 추정 →
• 크레딧과 사용량 →

처리량을 늘리기 전에 워크플로 검증하기

• 실제로 직렬화된 JSON, 파싱된 결과 경로, API 키 접근, 확정된 과금을 의도적인 테스트로 확인하세요. 알 수 없는 결과와 실패의 처리는 가능하면 예시 응답으로 테스트하세요.
• 워크플로의 어느 단계가 재시도하는지, 어떤 고객 필드가 변경되는지 확인하세요. 원본 레코드 ID, 완료된 응답, 요청 참조값을 보관해 두면 나중에 대상 시스템에서 실패가 발생해도 새 요청을 보낼 필요가 없습니다.
• 먼저 소규모로 통제된 실행만 활성화하고, 병렬 처리를 늘리기 전에 레코드와 크레딧을 확인하세요. GenderAPI의 크레딧과 자동화 플랫폼이 부과하는 작업(task) 또는 오퍼레이션 비용은 별개입니다.
• 일괄 요청에는 POST /api/v2/gender/batch를 사용하세요. API 키 접근 시 최대 50개 항목, IP 체험에서는 최대 10개 항목을 보낼 수 있습니다. items 배열에는 이름, 이메일 주소, 사용자 이름을 섞을 수 있으며, 항목마다 명시적인 옵션과 고유한 ID를 지정하세요. 모든 결과를 확인하세요. HTTP 200 응답에도 개별 항목의 실패가 포함될 수 있습니다. 기본 제공 커넥터가 일괄 요청을 지원하는지는 따로 확인해야 합니다.

• 일괄 요청과 개별 항목 실패 →
• Python 구현 가이드 →
• Node.js 구현 가이드 →

자주 묻는 질문