运行手册
一个 webhook，一次 HTTP 调用，一个决策。本运行手册指导无头 CMS 团队完成钩子、调用及失败情况的处理。
发布流程中的页面反向链接检查是一项小型任务。保持其精简。难点在于确定答案允许发生哪些变化，因为每月刷新一次链接图的数据无法单独否决某个页面。
我们建议检查机制发出警告、记录日志并让构建继续。默认设置可以更改。硬性阻断应仅用于你完全控制的内容，例如标记错误或缺少 canonical 标签。链接数据是一种信号，而信号会随时间漂移。
将其写下来。在编码之前先完成这一步。一条简单的策略，如“警告编辑、标记条目、永不阻止部署”，可以避免在发布日 6 pm 时发生冗长的争论。它还能让下一位工程师清楚哪些失败是预期行为，哪些是 bug，这比看起来更重要。建议每季度审查一次。
订阅 CMS 的发布事件。Contentful、Sanity 和 Strapi 可以在条目发布时调用您拥有的 URL，Storyblok 和 Payload 也提供 webhook 或 hooks。过滤包含出站 URL 或规范 URL 的内容类型。
API 在 q 中接受域名，因此 https://www.example.com/blog/post?x=1 必须先转换为 example.com。确定您对 www 的处理方式，并在构建任何内容之前，使用免费的 domain 操作测试一个真实域名。
overview 免费。如果返回结果稀疏，说明该域名可能较新，或尚未被我们的索引收录。这并不代表存在任何问题。
当规则指示需要进一步查看时，请调用 backlinks 并设置 per=100。无论返回多少行，费用均为 2 积分，因此请获取一页有足够数据的结果，而非多次获取少量数据。
在自定义字段中存储简短的结论以及检查日期。原始响应会使条目臃肿且随时间推移而陈旧，因为索引每月都在更新。
HTTP 401 表示密钥缺失或错误，因此需提醒人工介入。HTTP 402 表示额度已耗尽。其他任何错误：记录日志，跳过检查，让发布继续进行。
每次付费调用都携带你的密钥，要么在查询字符串中，要么在 Bearer 头中。优先使用 Header。查询字符串可能会出现在服务器日志和代理追踪中，而 Header 通常不会。
将密钥作为秘密存储在托管平台中，切勿存储在条目本身中。编辑可以查看他们有权访问的任何字段，但函数的环境变量通常仅对负责部署的人员可见。
泄露的密钥可能会消耗你账户中的余额，因此请像对待密码一样对待它。将其移出代码仓库和 CMS，如果日志文件中以明文形式出现，请立即轮换密钥。
使用钩子名称标记自己的日志。这样即使多个钩子共享同一个账户，也很容易将消耗追溯到一个函数。
可以，只要工具包含纯 HTTP 请求步骤。许多自动化工具都可以发送带有查询字符串的 GET 请求并读取返回的 JSON，因此免费概览操作完全不需要代码。
先从免费操作开始。每次草稿保存时触发的流程可能会比编辑察觉到的更快消耗额度，因此在免费调用平稳运行一段时间后，再添加付费步骤。
402 表示余额已空。它并不表示页面有问题。跳过付费检查，记录事件，并向负责充值账户的人员发送一条警报，然后让发布继续进行。
将余额警报阈值设置在远高于零的位置，以便在仍有时间充值时收到警告。重试循环在此处无效，因为每次调用都会以相同的方式失败，直到有人添加额度。成本表 中有具体数据。
在钩子自动执行之前，先针对你已知的一个域名运行一次。阅读第二个响应中的 _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 而失败。
有可能。最诚实的验证方式是直接提问。对您熟悉的一个网站，分别对两种表单运行免费域名检测，然后并排比较两次返回的结果。
无论选择哪条规则，都请将其写在代码注释中，以便后续工程师无需猜测。写注释成本为零，却能避免日后漫长的争论。
发送读者实际访问的主机地址，而非编辑多年前粘贴的链接。如果该链接存在重定向，请解析为最终目标地址，并忽略中间的重定向跳转。
独立子域名上的博客属于需要判断的情况。请提前决定是单独检查还是与其父域名一起检查，并将该决定记录在规则旁边。
每条被跳过的检查都生成一条日志行，这是成本最低的审计追踪方式。记录条目 ID、发送的域名、状态码以及是否执行了付费步骤。通常这就足够了。
存储的备注保持简短并标注日期，如上所述。完整的响应应记录在您自己的日志中（如果确实需要记录），因为它们体积较大且很快会过时。
从条目 ID 和发布版本开始。重复的 webhook 将显示为相同的两次配对，这正是您希望看到的结果。
添加域名、操作名称、状态码和调用开始时间。排除密钥本身，因为包含密钥的日志会成为密钥的第二个存储位置。
只要条目存在就保留，除非被更新的检查所替换。重要的是，读者能够判断备注的时效性，因为几个月前的备注看起来就像实时数据。
字段指南展示了我们建议用于该备注的四个字段，包括日期。
在任何人依赖钩子之前，运行以下四项检查。
使用已发布条目的副本触发钩子。将存储的备注与预期结果进行比较，并确认同一条目未被重复计费。
使用您新注册的合作伙伴域名。空值或内容稀少的响应应存储为“未知”，而非“失败”，并在备注中用通俗语言说明。
使用余额已耗尽的测试账户密钥运行钩子。确认跳过、日志行和告警均正常触发，且发布仍能成功到达构建阶段。
请团队外部的人大声朗读错误文本。如果他们无法说明下一步该怎么做，请在发布日前重写该提示。事后复盘展示了模糊的提示曾让一个虚构团队付出了什么代价。
我们的索引大约每月刷新一次。上次刷新后添加的链接将不会显示，而自上次刷新后移除的链接可能仍会显示。如需当天证明，请使用 Google Search Console 中的链接报告。
