ランブック
1つのWebhook、1つのHTTP呼び出し、1つの判断。このランブックは、ヘッドレスCMSチーム向けに、フック、呼び出し、およびエラーケースを解説します。
リリースフロー内でのページバックリンクチェックは小さなタスクです。小さく保ちましょう。難しいのは、その結果が何を変更できるかを決定することです。月次で更新されるリンクグラフでは、ページ単体で他のページを却下することはできません。
ゲートは警告を発し、ログを残し、ビルドを続行させることを推奨します。デフォルトは変更可能です。ハードブロックは、マークアップの破損やcanonicalタグの欠如など、あなたが管理できる領域に留めるべきです。リンクデータはシグナルであり、シグナルは変動するものです。
それを文書化してください。コードを書く前にそうしてください。「編集者に警告し、エントリーにタグを付け、デプロイを止めない」といった1行のポリシーは、リリース当日の午後6時に長々しい議論を避けるのに役立ちます。また、次のエンジニアにとって、どの失敗が意図的なものなのか、どのバグなのかを判断する手がかりとなります。これは見た目以上に重要です。四半期ごとにレビューしてください。
CMSの公開イベントを購読する。Contentful、Sanity、Strapiは、エントリが公開された際にあなたが管理するURLを呼び出すことができ、StoryblokとPayloadもWebフックやフックを提供しています。外部リンクや正規URLを含むコンテンツタイプにフィルターを適用してください。
APIはqにドメインを受け取るため、https://www.example.com/blog/post?x=1はまずexample.comに変換する必要があります。wwwの扱いを一度決定し、構築する前に無料のdomainアクションで実際のドメインをテストしてください。
overviewは無料です。結果が薄いと返ってきた場合、そのドメインは新しいか、私たちのインデックスで単に未登録である可能性があります。それは必ずしも悪い証拠ではありません。
ルールで「より詳しく確認する」と指示された場合は、backlinks を per=100 で呼び出します。これは行数に関係なく 2 クレジットなので、小さなリクエストを 10 回行うのではなく、有益な行数のページを 1 回で取得してください。
自分のフィールドに短い判定結果とチェック日付を保存してください。生データはエントリを肥大化させ、インデックスが毎月更新されるにつれて古びてしまいます。
HTTP 401はキーが不足しているか誤りであることを意味し、人間にアラートを出します。HTTP 402はクレジットが枯渇したことを意味します。その他のエラーの場合は、ログに記録し、チェックをスキップして公開を続行します。
すべての有料呼び出しには、クエリ文字列またはBearerヘッダーにキーが含まれます。ヘッダーを優先してください。クエリ文字列はサーバーログやプロキシのトレースに含まれる可能性がありますが、ヘッダーは通常それらに含まれません。
キーはホスティングプラットフォームのシークレットとして保存し、エントリ自体には保存しないでください。編集者はアクセス可能なフィールドはすべて閲覧できますが、関数の環境変数は通常、デプロイを管理する人々だけが参照可能です。
漏洩したキーはアカウントのクレジットを消費する可能性があるため、パスワードのように扱ってください。リポジトリやCMSから除外し、ログファイルにプレーンテキストで表示された場合はキーをローテーションしてください。
フックの名前でログにタグを付けます。これにより、複数のフックが同じアカウントを共有している場合でも、支出を1つの関数に簡単に遡って追跡できます。
ツールにプレーンなHTTPリクエストステップがある場合、可能です。多くの自動化ビルダーはクエリ文字列付きのGETを送信し、JSONを戻すことができるため、無料の概要アクションにはコードは不要です。
まず無料アクションのみから始めます。ドラフト保存時にトリガーされるフローは、編集者が気づく前にクレジットを消費する可能性があります。無料呼び出しがしばらく静かに動作してから、有料ステップを追加してください。
402は残高が空であることを意味します。ページの状態については何も示しません。有料チェックをスキップし、イベントをログに記録し、アカウントにクレジットを追加する担当者に1つのアラートを送信してから、公開を続行します。
残高のアラームを0より十分に高い値に設定し、警告がまだクレジットを追加する時間がある間に届くようにしてください。リトライループはここでは役立ちません。誰かがクレジットを追加するまで、すべての呼び出しが同じ方法で失敗するためです。コストテーブルに数値が記載されています。
フックが実行する前に、知っているドメインに対してこれらを1回実行してください。2番目のレスポンスの_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はまず短縮する必要があります。その短縮処理を1つの関数に1回記述してください。その後、実際のURLでテストします。
相対リンクやスキームの欠如は、フックを破綻させる一般的なケースです。クリーンな例で機能する短縮処理でも、編集者が午後5時に貼り付ける雑多なURLでは失敗する可能性があります。
可能性はあります。確実な確認方法は、実際に問い合わせてみることです。ご存知のサイトの両方のフォームで無料ドメインアクションを実行し、2つの応答を並べて比較してください。
どのルールを選択しても、次のエンジニアが推測しなくて済むように、コードコメントに書き込んでおきましょう。コメントはコストがかからず、後の長い議論を防ぐことができます。
読者が実際にアクセスするホストを指定してください。何年か前に編集者が貼り付けたリンクではありません。そのリンクがリダイレクトする場合は、最終的なアドレスに短縮し、中間のホップは無視してください。
独立したサブドメイン上のブログは、判断が分かれます。親ドメインと個別にチェックするか、一緒にチェックするかを事前に決定し、その選択をルールの横に書き留めてください。
チェックをスキップした際のログ行は、構築できる最も安価な監査証跡です。エントリID、送信したドメイン、ステータスコード、および有料ステップが実行されたかどうかを記録してください。通常、それで十分です。
上記の手順にあるように、保存されたノートは短く、日付付きのままにしてください。完全なレスポンスは、サイズが大きく、古くなりやすいため、ログに属する場合は独自のログに格納してください。
エントリIDと公開バージョンから始めましょう。同じWebhookが2回表示されるため、まさに確認したい内容が確認できます。
ドメイン、アクション名、ステータスコード、呼び出し開始時刻を追加してください。ログにキーが含まれると秘密が2か所で管理されることになるため、キー自体は除外してください。
エントリの存続期間中、または新しいチェックで置き換えられるまでです。重要なのは、読者がノートの古さを判断できることで、数ヶ月前のノートは生データのように見える可能性があります。
スコアフィールドガイドには、日付を含む、そのノート用に推奨する4つのフィールドが示されています。
フックに依存する前に、これらの4つのチェックを実行してください。
すでに公開したエントリのコピーでフックをトリガーします。保存されたノートと期待値を比較し、同じエントリが2回請求されていないことを確認してください。
あなたにとって新しいパートナードメインを使用してください。空または薄っぺらい回答は、失敗ではなく「不明」として保存され、その旨を明確な言葉でノートに記載してください。
残高を空にしたテストアカウントのキーを使用してフックを実行します。スキップ、ログ行、アラートがすべて発火し、公開がビルドに到達することを確認してください。
チーム外の誰かにエラーテキストを声に出して読んでください。次に何をすべきか言えない場合、公開日前にメッセージを書き直してください。ポストモーテムでは、あいまいなメッセージが1つの架空のチームにどれだけのコストをかけたかが示されています。
当社のインデックスは約1か月に1回更新されます。最終更新後に追加されたリンクは表示されず、削除されたリンクは依然として表示される可能性があります。同日の証明には、Google Search Consoleのリンクレポートを使用してください。
