Google Sheets 이메일 조회: 이메일로 행 찾기

Google Sheets 이메일 조회는 웹훅으로 이메일 주소를 받아 유효성을 검사한 뒤 비공개 Google Sheets 탭을 검색하여 처음 일치하는 행을 반환합니다. 이 템플릿은 AI 모델 없이 표준 워크플로 구성 요소를 사용합니다.

상태: 2026년 10월 9일에 AI Flowi Workflow 1.9.2 운영 환경에서 테스트 완료(30개 사례 모두 통과)

작성: Ai Flowi · 게시일 2026년 10월 9일 · 수정일 2026년 10월 9일

작업

email 열을 기준으로 행 하나를 조회합니다. 확인된 동작은 HTTP 200과 found:true 및 설정된 행 필드를 반환하거나, HTTP 404와 정확히 {"found":false}를 반환하는 것입니다. 일치 여부는 대소문자를 구분하며, 앞뒤 공백을 제거하거나 소문자로 변환하지 않습니다.

대상 사용자

신뢰할 수 있는 백엔드에서 소규모 비공개 스프레드시트의 내부 레코드를 조회하려는 팀을 위한 템플릿입니다. 개인정보는 호출자의 접근 권한을 확인한 후에만 제공해야 합니다. API 키만으로 모든 이메일의 행을 열람할 권한이 부여되는 것은 아닙니다.

입력 예시

{"email":"lookup@example.com"}

JSON을 보낼 때 Content-Type: application/json 헤더와 비공개 x-api-key 헤더를 포함합니다. 모든 예시에는 가상 데이터를 사용합니다.

설정

1. 사용할 Google 연결을 승인하고 비공개 테스트 탭을 만듭니다. 1행의 헤더를 email,name,status,note 순서로 설정합니다. 헤더는 중복 없는 소문자로 작성하고 가상 테스트 행을 추가합니다.
2. 아래의 노드 8개를 추가합니다. Universal Webhook에서 POST, Platform API Key를 선택하고 POST 응답 모드를 From Flow로 설정합니다. Production Endpoint를 복사하여 신뢰할 수 있는 요청 전송 시스템에 입력합니다.
3. Search Row에서 승인된 Google Account, 비공개 Spreadsheet ID 및 Sheet Name을 선택합니다. Key Column을 email, Header Row를 1로 설정하고 Case Sensitive Key Match를 활성화합니다.
4. 각 JSON Operations에서 JQ Expression을 선택하고 query 필드가 표시된 상태로 유지합니다. 아래 쿼리를 붙여 넣고 표에 명시된 포트를 정확히 연결합니다.
5. 두 Webhook Response 노드에서 기본 HTTP Status를 200 OK, Content Type을 application/json, Additional Response Headers를 Cache-Control: no-store로 설정합니다. 연결된 Response Definition이 기본값을 200, 404 또는 422로 덮어씁니다.
6. 비공개 레코드를 처리하기 전에 가상 테스트 데이터로 전체 체크리스트를 실행합니다. 각 요청 전후의 탭 전체를 비교합니다.

노드 연결 및 필드 매핑

아래 내부 포트 이름은 설정 가이드와 일치합니다. 여러 번 사용되는 JSON Operations 및 Webhook Response 노드는 각각 다른 ID를 갖습니다.

유효성 검사: JSON-validate

def reject: {verified:false, status_code:422, body:{error:"Invalid email", code:"INVALID_EMAIL"}};
.body as $b
| if ($b|type) != "object" then reject
  elif ($b.email|type) != "string" then reject
  elif ($b.email|length) < 1 or ($b.email|length) > 254 then reject
  elif ($b.email|test("^[^@[:space:]]+@[^@[:space:]]+[.][^@[:space:]]+$")) then {verified:true, email:$b.email}
  else reject end

검색 키: JSON-key

{email:.email}

유효성 검사를 통과한 이메일만 Search Row의 Search Data(row_data)에 전달됩니다. 스프레드시트, 탭 및 응답 필드는 고정된 설정이며 호출자가 덮어쓸 수 없습니다.

응답: JSON-response

if .found == true then
  if (.row|type) != "object" then error("Unexpected lookup result")
  else {status_code:200, body:{found:true, row:{email:.row.email, name:.row.name, status:.row.status, note:.row.note}}} end
elif .found == false then {status_code:404, body:{found:false}}
else error("Unexpected lookup result") end

연결 대상은 Response Definition입니다. Response Body에 연결하지 않습니다. 숫자형 status_code는 HTTP 상태 코드를 정하고, body는 JSON을 제공합니다. 이를 통해 완료된 조회 응답에서 원본 시트 ID, 연결 값, 행 번호 및 Google 메타데이터를 제외합니다.

관련 자료: Google Sheets 자동 기록: 예약 실행으로 상태 행 저장하기.

민감한 정보를 제거한 요청 및 응답 예시

운영 환경에서 가상 데이터로 테스트하여 확인한 응답입니다. 실제 엔드포인트나 인증 정보는 포함되어 있지 않습니다.

POST https://workflow.aiflowi.com/api/v1/webhook/<your-flow-id>
Content-Type: application/json
x-api-key: <your-private-key>

{"email":"lookup@example.com"}

일치하는 행이 있을 때 확인된 응답: HTTP 200.

{"found":true,"row":{"email":"lookup@example.com","name":"Synthetic First","status":"active","note":"first row"}}

일치하는 행이 없는 경우 확인된 응답(absent@example.com): HTTP 404.

{"found":false}

입력이 거부된 경우 확인된 응답({}): HTTP 422.

{"error":"Invalid email","code":"INVALID_EMAIL"}

유효성 검사 및 실패 시 동작

본문은 객체여야 합니다. 이메일은 1~254자의 문자열이어야 하며, @ 기호가 하나 있어야 하고 도메인에 마침표(.)가 포함되어야 하며, 공백이 없어야 합니다. 비어 있거나 텍스트가 아니거나 형식이 잘못된 주소는 시트를 읽기 전에 거부됩니다. 추가 필드는 무시합니다. 이 간단한 검사는 이메일 수신 가능 여부나 사서함 소유권을 확인하지 않습니다.

API 키가 없거나 유효하지 않으면 HTTP 403이 반환되었습니다. 형식이 잘못된 JSON에는 문서에 명시된 INVALID_EMAIL 객체와 함께 HTTP 422가 반환되었습니다. 워크플로 내부 응답은 JSON 콘텐츠 유형과 Cache-Control: no-store 헤더를 포함했습니다. 플랫폼의 403 응답은 JSON 콘텐츠 유형을 사용했지만 no-store 헤더는 없었습니다.

Search Row는 탭 전체를 읽고 헤더 아래에서 실제 행 순서상 처음 일치하는 행을 선택합니다. 기존 중복 행은 변경하지 않습니다. 행 끝의 note 값이 누락되면 JSON null이 됩니다.

이 그래프는 Google 오류를 처리하지 않습니다. 접근 권한, 헤더, 할당량 또는 스프레드시트 오류로 실행이 중단되면 가공되지 않은 플랫폼 오류가 반환될 수 있으며, HTTP 상태 코드는 404 또는 500일 수 있습니다. 이 응답은 워크플로에서 제어하는 404 {"found":false} 응답과 구별됩니다. 비공개 시트 메타데이터가 포함될 수 있고 설정한 응답 헤더가 적용되지 않을 수 있습니다. 결과를 외부에 제공하기 전에 설정을 확인하고 신뢰할 수 있는 백엔드에서 오류를 처리하세요.

테스트 결과

운영 환경에서 순차적으로 실행한 요청 30개가 모두 통과했습니다. 각 요청 후에도 데이터 행 5개와 모든 값이 그대로 유지되었습니다. 임시 API 키가 삭제된 것도 확인했습니다. 본문이 객체가 아닌 그룹과 이메일 값이 유효하지 않은 그룹에는 각각 요청 5개가 포함됩니다.

다운로드

노드 설정, JQ 및 포트 정보가 담긴 인증 정보가 포함되지 않은 설정 가이드를 다운로드하세요. 이 파일은 설정 가이드이며, 가져올 수 있는 워크플로 파일이 아닙니다.

설정 JSON 다운로드

가져올 수 있는 워크플로 파일은 제공되지 않으며, 가져온 워크플로 사본 테스트도 실시하지 않았습니다. 실제 환경에서 워크플로를 구축하고 인증 정보를 검토한 뒤 가져온 사본을 테스트하면 민감한 정보를 제거한 가져오기 파일을 추가할 수 있습니다. 그전까지는 문서에 명시된 노드와 매핑을 직접 구성하세요.

필수 설정

• AI Flowi Workflow 워크스페이스와 요청 전송 시스템용 비공개 Platform API Key.
• 비공개 스프레드시트에 접근할 수 있는 승인된 Google 연결.
• 비공개 Spreadsheet ID와 설정된 조회 탭. 호출자가 제공한 식별자는 사용하지 마세요.
• 중복 없는 소문자 email,name,status,note 헤더를 1행에 설정합니다. 다른 스키마가 필요하면 응답 필드 구성을 신중하게 조정하세요.
• 일치, 불일치, 대소문자 차이, 중복 및 빈 셀을 확인할 가상 테스트 행과 호출자의 접근 권한을 확인할 신뢰할 수 있는 백엔드.

테스트한 버전 및 날짜

2026년 10월 9일 (MYT) AI Flowi Workflow 1.9.2 운영 환경에서 테스트했습니다. 이 검증 자료에는 실제 실행 시 노드 과금 측정 결과나 가져온 워크플로 사본의 검증 결과가 포함되어 있지 않습니다.

사용량 및 비용 산정 전제

요금제: Go 연간 결제 시 월 USD8부터(월간 USD10), Plus 월 USD16부터(월간 USD20), Pro 100 월 USD80부터(월간 USD100), Pro 200 월 USD160부터(월간 USD200), Pro 500 월 USD400부터(월간 USD500). 매월 5,000~250,000 Flowi Tokens가 제공되며 충전도 가능합니다. 노드 실행 1회당 1토큰, 타사 API 및 모델 사용 요금은 포함되지 않습니다.

선택된 실행 경로의 예상 노드 실행 횟수는 일치하는 행이 없는 경우를 포함한 유효한 조회에서 7회, 유효성 검사 거부에서 4회, 플랫폼의 키 거부에서 그래프 노드 실행 0회입니다. 이는 구조에 따른 추정치이며 실제 실행 검증 자료가 필요합니다. 시트 오류가 발생하면 노드 4개가 실행을 완료한 뒤 검색 시도가 실패합니다. 실패한 노드의 과금 여부는 확인되지 않았습니다.

여러 유형의 요청이 섞여 있다면 예상치는 7 × valid + 4 × invalid로 계산합니다. 재시도할 때마다 선택된 경로가 다시 실행됩니다. 테스트 모음의 추정치는 웹훅 요청 처리에 필요한 예상 노드 실행 139회와 데이터 재조회용 단일 노드 실행 31회를 합산한 값입니다. 모든 요청이 재시도 없이 완료되면 예상 사용량은 170 Flowi Tokens입니다. 카탈로그 조회, 그래프 저장 및 이벤트 폴링은 노드 실행에 해당하지 않습니다.

모델 구성 요소나 타사 유료 API는 필요하지 않습니다. 타사 API 및 모델 사용료는 요금제에 포함되지 않습니다. Google 계정의 접근 권한과 API 할당량은 여전히 적용됩니다. 토큰 초과 사용 요금이나 추가 요금제 혜택은 가정하지 않습니다.

제한 사항

• 탭 전체를 읽고 선형 검색을 수행하므로 대량 처리를 위한 데이터베이스 인덱스로는 적합하지 않습니다.
• 키를 대소문자까지 정확히 비교하므로 시트 값의 대소문자가 다르거나 앞뒤에 공백이 있으면 찾지 못할 수 있습니다. 중복이 있으면 첫 번째 행을 선택합니다. 외부에서 동시에 수정하면 결과가 달라질 수 있습니다.
• 헤더와 반환되는 셀 값은 설정된 스키마와 일치해야 합니다. 수식 및 서식이 적용된 값은 Google API 기본 동작을 따릅니다.
• 이 그래프는 이메일별 접근 권한 확인, Google 오류 복구 또는 스냅샷 격리를 제공하지 않습니다.
• 값 비교로는 수식, 서식, 권한 또는 다른 탭을 검증할 수 없습니다. 운영 환경의 HTTP, 본문 및 값 검사는 통과했지만 가져온 사본의 검증은 아직 테스트하지 않았습니다.

다음 단계

자신의 비공개 설정에서 체크리스트를 다시 실행하세요. 키 삭제와 가공되지 않은 오류 처리를 검토한 다음, 가져온 사본에서 민감한 정보를 제거하고 다시 테스트한 후에 다운로드 파일을 운영 환경 테스트가 완료된 것으로 취급하세요.

관련 문서: Universal Webhook · Google 연결 · 웹훅에서 Google Sheets로 연결하는 튜토리얼 · 활용 사례.