엔지니어링
파이프라인에 링크 데이터를 넣되, 파이프라인을 깨뜨리지 마세요
테이블을 한 번 가져오는 것은 쉽습니다. 매월 1년 동안 조용한 공백 없이 가져오는 것이 진짜 작업입니다.
SEOCheck 연구팀 ·

12줄로 작성하는 월간 작업
파이썬, 표준 라이브러리만 사용. 참조 도메인을 페이지네이션하며 큰 오류 발생 시 중단합니다. 각 응답은 행을 rows에 넣습니다. 더 큰 페이지를 위해 per(10~5000)를 추가하고, 루프는 total 행을 읽을 때까지 멈춥니다.
import json, urllib.request as u
KEY='sk_live_...'
def get(**p):
q='&'.join(f'{k}={v}' for k,v in p.items())
url=f'https://seocheck.dev/api.php?{q}&key={KEY}'
with u.urlopen(url) as r:
return json.load(r)
rows, page = [], 1
while True:
d = get(action='refdomains', q='example.com', page=page)
if not d['ok']: raise SystemExit(d)
rows += d['rows']
if not d['rows'] or len(rows) >= d['total']: break
page += 1
print(len(rows), 'of', d['total'], 'balance', d['_credits']['balance'])SEO 백링크 API 작업이 조용히 실패하는 이유
크래시가 아니라, 마지막 페이지가 누락된 테이블로 실패합니다. 일반적인 원인은 카운트가 아닌 추측으로 끝나는 루프입니다.
매번 실행 시 세 가지를 확인하세요. ok가 true로 반환되었나요? 행 수가 total에 도달했나요? _credits가 예상 잔액을 보여주나요? 답변이 '아니오'인 경우 작업을 실패 처리하고 누군가에게 알리세요.
조용한 성공은 큰 실패보다 더 나쁩니다. 잘못된 행으로 완료된 작업은 시트를 읽기 전까지 건강해 보입니다.
여기서는 많은 API와 달리 속도 제한과 느린 응답이 덜 중요합니다. 월간 작업은 1시간 후 단순히 재시도할 수 있습니다. 중요한 것은 재시도가 이미 성공한 호출에 대해 이중 과금하지 않는지 확인하는 것입니다. 각 실행 전후에 _credits 잔액을 로깅하고 비교하세요. 예상 비용보다 큰 점프가 발생하면 루프가 돌고 있다는 의미입니다. 다음 실행 전에 조사하세요.
이미 Airflow나 작은 서버의 일반 cron을 실행하는 팀은 새로운 도구가 필요하지 않습니다. GitHub Actions 스케줄도 작동합니다. 구조는 동일합니다: 가져오기, 검증, 저장, 알림. 스위트 내보내기와 비교 중이라면 비용 비교를 참조하세요.
일반적인 ingestion 함정
| 함정 | 증상 | 해결책 |
|---|---|---|
| 페이지네이션 후 클라이언트 측 필터링 | 느린 실행, 낭비된 페이지 | sort와 order를 서버 측에서 사용하고 잘라내기 |
| 캡을 넘어선 페이지네이션 | 루프가 끝나지 않음 | 깊은 페이지네이션은 50,000행에서 중단됩니다. 이에 대비하세요 |
| HTTP 402를 버그로 처리 | 작업이 무한 재시도 | 402는 크레딧이 부족함을 의미합니다. 재시도가 아닌 충전 |
| 401을 일시적 오류로 처리 | 동일 | 잘못된 키; 알림 및 중단 |
| 무작위 월 비교 | 유령 감소 | 인덱스는 월별로 새로 고쳐집니다. 유사한 항목끼리 비교하세요 |
| 점수 벤더 혼합 | 무의미한 추세 | 시트당 하나의 소스 |
전체 작업에 대한 합리적인 구조
도메인 목록을 한 곳에 보관
시트나 테이블. 처음에는 도메인 열만 포함합니다.
bulk_dr로 목록 점수 매기기
호출당 최대 2,000개 도메인, 크레딧 1개. domains=로 GET하거나 길면 본문을 POST하세요.
생존자만 세부 정보 가져오기
상위 슬라이스에 refdomains 또는 anchors를 실행합니다. 호출당 크레딧 2개, 각기 최대 1,000행.
덮어쓰기 대신 스냅샷 저장
모든 가져오기에 날짜를 매깁니다. 추세에는 역사가 필요합니다.
변경 사항 알림
벤더 도메인에서 DR이 몇 포인트 떨어지면 메시지 가치가 있습니다.
Google Sheets 및 CORS
CORS가 열려 있으므로 브라우저 스니펫이나 Apps Script가 API를 직접 호출할 수 있습니다. 셀 함수를 위한 작은 예시입니다. 이 함수는 셀의 도메인에 대한 도메인 평판(DR)을 반환합니다.
function DR(domain){
var url='https://seocheck.dev/api.php?action=domain&q='+encodeURIComponent(domain);
var r=JSON.parse(UrlFetchApp.fetch(url).getContentText());
return r.metrics.dr;
}
신선함과 정직함
인덱스는 자체 크롤러로 월 약 한 번 재빌드됩니다. 지연이 있을 수 있습니다. 몇 주 이상된 데이터는 정상입니다. 시간당 가져오기를 예약하지 마세요. 동일한 데이터를 반환하고 크레딧을 소모합니다.
가능하면 리프레시 다음 날을 선택하세요. 그렇지 않으면 매월 같은 날 실행하고 작은 지연을 수용하세요.
전체 키워드 스위트, 일일 크롤링 및 랭킹 트래킹은 다른 곳에 있습니다. Ahrefs와 Semrush가 이를 커버합니다. 무언가를 복제하기 전에 비용 비교를 읽으세요. 엔드포인트 참조에는 모든 매개변수가 있습니다.

신뢰할 수 있는 작업 설계
파이프라인은 가장 약한 실행만큼만 좋습니다. 각 실행에 증거를 남기도록 구축하여, 나쁜 달을 추측이 아닌 설명할 수 있게 만드세요. 추가 작업은 작습니다. 나중에 많은 논쟁을 줄이고 크레딧도 절약합니다.
네 단계로 생각하세요: 가져오기, 검증, 저장, 알림. 각 단계를 단순하게 유지하세요. 각 단계는 자체적으로 실패할 수 있어야 하며, 각 실패는 어느 단계가 깨졌는지 말해야 합니다. 이 네 단계는 작성 언어에 관계없이 모든 SEO 백링크 API 작업에 적용됩니다.
변환하기 전에 원본 응답 저장
날짜와 호출 매개변수가 파일 이름이나 헤더 행에 포함된 상태로 JSON을 그대로 저장하세요. 분기 중 숫자가 이상해 보일 때, 누군가가 편집한 시트가 아닌 API가 실제로 말한 내용으로 돌아가야 합니다.
원본 파일 보관 비용은 적습니다. 세 번 덮어쓴 스프레드시트는 3월에 무슨 일이 있었는지 알려줄 수 없습니다.
행 수와 잔액을 포함한 실행 로그 유지
각 실행은 로그에 한 줄을 추가해야 합니다: 시작 시간, 호출한 내용, 반환된 행 수, total 값 및 _credits의 잔액. 숫자가 움직일 때 로그가 첫 번째 확인 장소입니다.
반환된 행 수가 total과 일치하지 않으면 실행이 불완전합니다. 실패로 표시하고 부분 파일을 유지하며 추세에 병합하지 마세요.
재시도와 다시 실행 분리
재시도는 답 없이 실패한 호출을 반복합니다. 다시 실행은 완료되었지만 다시 수행해야 하는 전체 작업을 반복합니다. 다르게 취급하세요. 실제로 성공한 호출의 재시도는 크레딧을 두 번 소모할 수 있기 때문입니다.
호출이 성공했는지 알 수 없다면 다시 보내기 전에 로그를 읽으세요. 이 습관은 대부분의 놀라움 요금을 방지합니다.
중요한 실패에 알림
누군가가 알림에 반응할 때만 유용합니다. 실패한 키, 빈 잔액, total과 일치하지 않는 행 수 및 예상치보다 훨씬 높은 비용에 대해 보내세요. 일상적인 성공을 메시지에 넣지 않으면 사람들은 읽기를 멈춥니다.
크레딧 낭비 없이 스케줄링
스케줄은 시계가 아닌 데이터를 따라야 합니다. 시간당 실행되는 작업은 하루에 같은 스냅샷에 24번 지불합니다. 이것이 이 작업에 월별 리듬이 중요한 이유입니다.
스케줄을 한 번 선택하고 기록하세요. 매월 변경하는 것이 추세선에 인공적인 단계를 추가하는 방법입니다.
이 데이터에는 시간당보다 월별이 낫습니다
인덱스는 월 약 한 번 재빌드됩니다. 그보다 자주 가져오면 동일한 데이터를 반환하고 크레딧을 소모합니다. 추가 실행이 필요하면 리프레시 중이 아닌 알려진 리프레시 후에 하세요.
하나의 작업, 여러 도메인
모든 도메인을 단일 목록에 넣고 한 번의 패스에서 점수 매깁니다. bulk_dr 호출은 크레딧 1개로 최대 2,000개 도메인을 처리하므로, 1,500개 잠재고객 목록은 10개 목록과 같은 비용이 듭니다. 도메인이 refdomains와 같은 더 깊은 데이터가 필요한 경우에만 작업을 분할하세요.
목록을 한 곳에 유지하세요. 도메인 목록의 두 사본은 어긋나고, 그러면 추세는 서로 다른 사이트 집합을 비교합니다.
누가 작업을 소유해야 하는가
공유 서버에서 실행되더라도 작업에 소유자를 한 명 지정하세요. 알림이 발생했을 때 답변하고, 잔액을 확인하며, 실패한 달에 다시 실행이 필요한지 결정할 누군가가 있어야 합니다. 소유자가 없으면 조용히 실패한 작업은 분기 동안 unnoticed로 갈 수 있습니다. 로그 헤더에 소유자 이름을 작성하여 다음 사람이 누구에게 물어봐야 하는지 알 수 있게 하세요.
먼저 작은 목록으로 테스트
작업을 변경할 때 전체 목록에 적용하기 전에 5개 도메인에서 실행하세요. 루프의 오류는 작은 샘플에서 몇 초 만에, 큰 샘플에서 크레딧으로 나타납니다. 5개 도메인 테스트는 거의 비용이 들지 않습니다. 5개 도메인은 루프를 보여주기에는 충분합니다.
테스트 목록을 저장소에서 작업 옆에 유지하여 매번 확인할 때 동일하게 유지하세요.
파이프라인이 잘못된 답변일 때
파이프라인은 동일한 숫자를 반복해서 필요로 할 때 그 자리를 얻습니다. 올바른 도구를 선택하세요. 단일 질문의 경우 수동 가져오기가 더 나은 도구일 수 있습니다. 실제로 필요한 것이 무엇인지 정직하게 판단하세요.
파이프라인을 건너뛰는 또 다른 이유는 작업의 형태입니다. 질문이 매주 변경되면 고정된 작업은 잘못된 것을 계속 측정합니다.
일회성 내보내기는 파이프라인이 아닙니다
단일 피치를 위해 한 경쟁사의 참조 도메인이 필요하다고 가정합니다. refdomains를 한 번 실행하고 파일을 저장한 후 넘어갑니다. 이를 위해 예약된 작업을 빌드하면 통찰력 없이 유지보수만 추가됩니다.
숫자가 다른 데이터와 만날 때
링크 데이터는 한 가지 종류의 질문에 답합니다. 키워드 랭킹, 전환 또는 통화 로그와 결합해야 한다면 결합을 자체 시스템에서 유지하고 링크 스냅샷을 하나의 입력으로 유지하세요. API가 다른 소스를 대신 보유하기를 기대하지 마세요.
무엇을 유지할지, 얼마나 오래 유지할지 결정
첫 실행 전에 저장할 필드와 당사에서 유지할 기간을 결정하세요. 필요 없는 행을 잘라내세요. 더 작은 파일은 고객이나 동료와 공유하기 쉽고 프로젝트가 끝날 때 삭제하기 쉽습니다.
엔드포인트 참조는 모든 필드와 각 호출의 비용을 나열하여 이 결정을 기록하기 쉽게 만듭니다.
사전 비행 목록
- 키는 저장소 대신 시크릿으로 저장.
- 루프는 희망이 아닌 행 수로 종료.
- HTTP 401 및 402 별도 처리.
- 스냅샷 날짜 표시 및 보관.
- 테이블당 하나의 점수 벤더.
- 시간당 아닌 월별 스케줄.