실행 매뉴얼
하나의 웹훅, 하나의 HTTP 호출, 하나의 결정. 이 실행 매뉴얼은 헤드리스 CMS 팀이 훅, 호출 및 오류 사례를 처리하는 방법을 안내합니다.
릴리스 흐름 내의 페이지 백링크 확인은 작은 작업입니다. 작게 유지하세요. 어려운 부분은 정답이 무엇으로 허용될지 결정하는 것입니다. 월간으로 갱신되는 링크 그래프는 자체적으로 페이지를 거부할 수 없습니다.
게이트는 경고하고, 로그를 남기고, 빌드를 계속 진행하도록 제안합니다. 기본값은 변경될 수 있습니다. 하드 블록은 손상된 마크업이나 누락된 canonical 태그와 같이 우리가 제어할 수 있는 항목에 해당합니다. 링크 데이터는 신호이며, 신호는 변동합니다.
기록하세요. 코딩하기 전에 그렇게 하세요. "편집자에게 경고하고, 항목에 태그를 붙이고, 배포를 중단하지 않는다"와 같은 한 줄 정책은 릴리스 당일 오후 6시에 긴 논쟁을 피하게 해줍니다. 또한 다음 엔지니어가 의도된 오류와 버그를 구분할 수 있게 해주며, 이는 생각보다 더 중요합니다. 분기별로 한 번 검토하세요.
CMS의 게시 이벤트에 구독하세요. Contentful, Sanity, Strapi는 항목이 게시될 때 소유한 URL로 호출할 수 있으며, Storyblok과 Payload도 웹훅 또는 훅을 제공합니다. 외부 링크나 canonical URL을 포함하는 콘텐츠 유형으로 필터링하세요.
API는 q에 도메인을 받습니다. 따라서 https://www.example.com/blog/post?x=1은 먼저 example.com이 되어야 합니다. www 처리 방식을 한 번 결정하고, 빌드하기 전에 무료 domain 액션으로 실제 도메인을 테스트하세요.
overview는 비용이 없습니다. 결과가 빈약하게 나오면 해당 도메인이 새로웠거나 인덱스에 단순히 알려지지 않았을 수 있습니다. 이는 나쁜 것의 증거가 아닙니다.
규칙이 더 자세히 보라고 하면 backlinks를 per=100로 호출하세요. 행의 수에 관계없이 이는 2 크레딧이므로, 작은 10개 대신 유용한 행의 페이지를 요청하세요.
검증 결과를 요약한 내용을 자체 필드에 저장하고, 검증 날짜도 함께 기록하세요. 원본 응답은 항목을 불필요하게 늘리고 시간이 지남에 따라 데이터가 노후화되므로 권장하지 않습니다. 인덱스는 매월 업데이트되기 때문입니다.
HTTP 401은 키가 누락되었거나 잘못되었음을 의미하므로 사람에게 알림을 보냅니다. HTTP 402는 크레딧이 소진되었음을 의미합니다. 그 외의 오류가 발생하면 로그를 기록하고 검증을 건너뛰며 게시가 완료되도록 합니다.
모든 유료 호출에는 쿼리 문자열 또는 Bearer 헤더를 통해 키가 전달됩니다. 헤더를 사용하는 것을 권장합니다. 쿼리 문자열은 서버 로그나 프록시 추적 기록에 남을 수 있지만, 헤더는 일반적으로 이러한 기록에 남지 않습니다.
키는 호스팅 플랫폼의 시크릿으로 저장해야 하며, 항목 자체에는 저장하지 마세요. 편집자는 접근 가능한 필드의 내용을 모두 읽을 수 있지만, 함수의 환경 변수는 일반적으로 배포를 관리하는 사람만 확인할 수 있습니다.
누출된 키로 계정 잔금이 소모될 수 있으므로 비밀번호처럼 취급하세요. 키는 저장소와 CMS에 남지 않도록 하고, 로그 파일에 평문으로 노출된 경우 키를 교체하세요.
훅의 이름을 사용하여 자체 로그에 태그를 지정하세요. 그러면 여러 훅이 동일한 계정을 공유하더라도 지출 내역을 특정 함수로 쉽게 추적할 수 있습니다.
네, 도구가 일반 HTTP 요청 단계를 지원한다면 가능합니다. 많은 자동화 빌더는 쿼리 문자열이 포함된 GET 요청을 보내고 JSON 응답을 읽을 수 있으므로, 무료 개요 액션에는 코드 작성만으로는 충분합니다.
먼저 무료 액션부터 시작하세요. 모든 초안 저장 시 트리거되는 플로우가 편집자가 인지하기 전에 크레딧을 빠르게 소모할 수 있으므로, 무료 호출이 안정적으로 작동하는 기간이 지난 후에 유료 단계를 추가하세요.
402는 잔금이 부족함을 의미하며, 페이지 상태와는 무관합니다. 유료 검증을 건너뛰고 이벤트를 로그에 기록한 후, 계정에 크레딧을 충전할 담당자에게 한 번의 알림을 보냅니다. 그런 다음 게시가 완료되도록 합니다.
경고 알림이 충전할 시간이 남아 있을 때 도착하도록 잔고 알람을 0보다 훨씬 높은 수준으로 설정하세요. 여기서 재시도 루프는 도움이 되지 않습니다. 누군가가 크레딧을 추가하기 전까지는 모든 호출이 동일한 방식으로 실패하기 때문입니다. 게시당 비용 표에 수치가 나와 있습니다.
훅이 자동으로 수행하기 전에 알고 있는 도메인에서 한 번 실행해 보세요. 두 번째 응답의 _credits 필드를 확인하세요.
# free, no key
curl -s "https://contentin.app/api.php?action=overview&q=example.com"
# 2 credits, key in a header
curl -s -H "Authorization: Bearer sk_live_..." \
"https://contentin.app/api.php?action=backlinks&q=example.com&per=100"API는 q 파라미터에 순수 도메인만 받으므로, 전체 URL은 먼저 단순화해야 합니다. 이 단순화 로직은 한 번만 작성하고 하나의 함수에 구현하세요. 그런 다음 실제 URL로 테스트하세요.
상대 링크와 프로토콜이 누락된 경우가 훅을 가장 많이 깨뜨립니다. 깔끔한 예제에서는 잘 작동하는 단순화 로직도 편집자가 오후 5시에 붙여넣는 지저분한 URL에서는 실패할 수 있습니다.
그럴 수도 있습니다. 가장 정직한 방법은 직접 확인해 보는 것입니다. 알고 있는 사이트의 도메인 두 가지 형태에 대해 무료 도메인 액션을 각각 실행한 후, 두 결과를 나란히 비교해 보세요.
어떤 규칙을 선택하든 코드 주석에 명시하여 다음 엔지니어가 추측하지 않도록 하세요. 주석은 비용이 들지 않지만, 나중에 긴 논쟁을 예방할 수 있습니다.
독자가 실제로 접속하는 호스트를 사용하세요. 편집자가 몇 년 전에 붙여넣은 링크가 아니라요. 해당 링크가 리다이렉션된다면 최종 주소로 축약하고 중간 경유지는 무시하세요.
서브도메인에 블로그를 만드는 것은 판단이 필요한 사안입니다. 독립적으로 검사할지, 상위 도메인과 함께 검사할지 미리 결정하고 그 선택 사항을 규칙 옆에 기록하세요.
검사 건너뛰기마다 로그 라인을 남기는 것이 가장 저렴한 감사 추적(Audit Trail)입니다. 항목 ID, 전송한 도메인, 상태 코드, 유료 단계 실행 여부를 기록하세요. 보통 이 정도로 충분합니다.
위 단계에서 언급한 대로 저장된 메모는 짧고 날짜가 명시되어야 합니다. 전체 응답은 크기가 크고 시간이 지나면 가치가 떨어지므로, 로그가 필요한 경우 자체 로그에 보관하세요.
항목 ID와 게시 버전으로 시작하세요. 그러면 중복된 웹훅이 동일한 쌍으로 두 번 나타나는 것을 확인할 수 있으며,这正是 원하는 결과입니다.
도메인, 액션 이름, 상태 코드, 호출 시작 시간을 추가하세요. 로그에 시크릿 키가 포함되면 비밀이 저장되는 두 번째 장소가 되므로 키 자체는 제외하세요.
항목이 존재하는 동안 유지하되, 새 검사 결과가 덮어쓰면 업데이트됩니다. 중요한 것은 독자가 메모의 경과 시간을 알 수 있어야 한다는 점입니다. 몇 달 된 메모는 실시간 데이터처럼 오해받을 수 있기 때문입니다.
점수 필드 가이드에는 날짜를 포함한 해당 메모를 위한 네 가지 필드 제안이 나와 있습니다.
누군가 후크에 의존하기 전에 다음 네 가지 검사를 실행하세요.
이미 게시한 항목의 복사본으로 후크를 트리거하세요. 저장된 메모를 예상 결과와 비교하고, 동일 항목이 중복 청구되지 않았는지 확인하세요.
새로운 파트너 도메인을 사용하세요. 빈 응답이나 정보가 부족한 경우, 실패로 처리하지 말고 '알 수 없음(Unknown)'으로 저장해야 하며, 메모에 이를 명확히 명시해야 합니다.
잔액을 모두 소진한 테스트 계정 키로 후크를 실행하세요. 건너뛰기, 로그 라인, 알림이 모두 정상적으로 작동하고 게시가 빌드 단계에 도달하는지 확인하세요.
팀 외부 사람에게 오류 텍스트를 소리 내어 읽게 하세요. 다음 행동을 알 수 없다면 출시 전에 메시지를 수정하세요. 사후 분석 보고서에서는 모호한 메시지가 한 가상 팀에 어떤 비용을 초래했는지 보여줍니다.
인덱스는 약 한 달에 한 번 업데이트됩니다. 마지막 업데이트 이후 추가된 링크는 표시되지 않으며, 제거된 링크는 여전히 나타날 수 있습니다. 당일 확인이 필요하면 Google Search Console의 링크 보고서를 사용하세요.
