エンジニアリング
リンクデータをパイプラインに流し込み、破綻させない
テーブルを一度だけ取得するのは簡単です。しかし、静かな欠落なく1年間毎月取得するのは本当の仕事です。
SEOCheckリサーチチーム ·

12行のPythonで実現する月次ジョブ
Python、標準ライブラリのみ使用。参照ドメインをページネーションで取得し、重大なエラーが発生した時点で停止します。各レスポンスの行は 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ジョブが静かに失敗する理由
クラッシュではなく、最後のページが欠落したテーブルとして現れます。主な原因は、カウントに基づかず、推測で終了するループです。
毎回の実行で3つのことを確認してください。ok が true を返しましたか?行カウントが total に達しましたか?_credits は期待する残高を示していますか?いずれの答えも「いいえ」の場合、ジョブを失敗させ、関係者に通知してください。
静かな成功は、大きな失敗よりも悪いです。間違った行で終了するジョブは、誰かがシートを読むまで健全に見えます。
レート制限や応答の遅延は、多くのAPIと比較するとここでは重要度が低くなります。月次ジョブであれば、1時間後に再試行するだけで済みます。重要なのは、既に成功した呼び出しに対して二重に課金されないように再試行することです。各実行前後の _credits 残高をログに記録し、比較してください。残高の増加分がジョブの予想コストを超えている場合、ループが重複している可能性があります。次の実行前にこれを調査してください。
すでにAirflowや小型サーバー上の単純なcronを実行しているチームは、新しいツールを必要としません。GitHub Actionsのスケジュールも有効です。構成は同じです:取得、検証、保存、アラート。スイートエクスポートと比較検討している場合は、コスト比較 を参照してください。
一般的なインジェスションの落とし穴
| 落とし穴 | 症状 | 修正方法 |
|---|---|---|
| ページネーション後のクライアント側フィルタリング | 実行の遅延、無駄なページ | sort と order をサーバー側で適用してから切り捨てる |
| 上限を超えたページネーション | ループが終了しない | ディープページネーションは50,000行で停止します;計画に組み込んでください |
| HTTP 402をバグとして扱う | ジョブが永遠に再試行する | 402はクレジットが枯渇したことを意味します;再試行せず、クレジットを追加してください |
| 401を一時的なエラーとして扱う | 同じ | 無効なキー;アラートを出して停止 |
| 無作為に月を比較する | ファントム(幻の)減少 | インデックスは月次で更新されます;同様の条件で比較してください |
| スコアベンダーの混在 | 意味のないトレンド | シートごとに1つのソースのみ |
全体としての適切な構成
ドメインリストを一箇所に保持する
シートまたはテーブル。最初はドメインの1列のみ、それ以外は何も入れない。
bulk_dr でリストのスコアリングを行う
1回の呼び出しで最大2,000ドメイン、クレジット1つ。domains= でGETするか、リストが長い場合はPOSTでボディとして送信します。
生存者(上位ドメイン)のみ詳細を取得する
上位層に対して refdomains または anchors を実行します。1回の呼び出しでクレジット2つ、最大1,000行ずつ取得可能。
上書きではなくスナップショットを保存する
取得ごとに日付を付与。トレンド分析には履歴が必要です。
変更時にアラートを出す
ベンダードメインでDRが数ポイント低下した場合、それはメッセージを送る価値があります。
Google SheetsとCORS
CORSは開放されているため、ブラウザスニペットやApps ScriptからAPIを直接呼び出すことができます。セル関数のための小さな例。この関数は、セル内のドメインのDomain Ratingを返します。
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;
}
鮮度と誠実さ
インデックスは当社のクローラーから約1ヶ月ごとに再構築されます。遅延が発生することを想定してください。数週間前のデータは通常です。時間単位の取得をスケジュールしないでください。同じデータが返され、クレジットが消費されるだけです。
可能であれば更新日の翌日を選んでください。そうでない場合は、毎月同じ日に実行し、わずかな遅延を受け入れます。
完全なキーワードスイート、日次クローリング、ランク追跡は他のツールで提供されています。AhrefsとSemrushがそれらをカバーしています。何かを複製する前にコスト比較をお読みください。エンドポイントリファレンスにはすべてのパラメータが記載されています。

信頼できるジョブを設計する
パイプラインはその最も弱い実行にしか過ぎません。各実行で証拠を残せるように構築し、悪い月が推測ではなく説明できるようにします。余分な作業はわずかですが、後の議論を大幅に節約し、クレジットも節約できます。
取得、検証、保存、アラートの4つの段階で考えます。各段階をシンプルに保ちます。各段階は独立して失敗可能であり、各失敗はどの段階が壊れたかを明確に示すべきです。この4つの段階は、記述言語に関係なく、あらゆるSEOバックリンクAPIジョブに適用されます。
変換する前に生レスポンスを保存する
JSONを返されたそのままの形式で保存し、ファイル名またはヘッダー行に日付と呼び出しパラメータを含めます。翌四半期に数値がおかしい場合、誰かが編集したシートではなく、APIが実際に返した内容に戻ることができます。
生ファイルの保管コストはわずかです。3回上書きされたスプレッドシートは、3月に何が起こったかを教えてくれません。
行数と残高を含む実行ログを保持する
各実行はログに1行追加すべきです:開始時刻、実行された呼び出し、返された行数、total値、および_creditsからの残高。数値が変化したとき、まずログを確認すべきです。
返された行数がtotalと一致しない場合、実行は不完全です。失敗としてマークし、部分的なファイルを保持し、トレンドにマージしないでください。
リトライと再実行を分離する
リトライは回答なしで失敗した呼び出しを繰り返すことです。再実行は完了したが再実行が必要なジョブ全体を繰り返すことです。これらを異なるものとして扱ってください。実際には成功した呼び出しのリトライはクレジットを2回消費する可能性があるためです。
呼び出しが成功したかどうか判断できない場合、再送信する前にログを読んでください。この習慣だけで、ほとんどの予期せぬ請求を防ぐことができます。
重要な失敗に対してアラートを送信する
アラートは誰かがそれに対して行動したときにのみ有用です。失敗したキー、空の残高、totalと一致しない行数、予想される金額を大幅に上回るコストに対してアラートを送信してください。ルーチンの成功はメッセージから除外してください。そうしないと、人々はそれを読まなくなります。
クレジットを無駄にせずにスケジュールする
スケジュールは時計ではなくデータに従うべきです。毎時間実行されるジョブは、1日24回同じスナップショットに対して課金されます。これが、この種の作業において月次リズムが重要である理由です。
スケジュールを1回選択し、記録してください。毎月それを変更すると、トレンドラインに人工的なステップが混入します。
このデータには月次が時間次より優れています
インデックスは約1ヶ月に1回再構築されます。それより頻繁に取得すると、同じ結果が返され、クレジットが消費されます。追加の実行が必要な場合は、既知の更新の後に実行し、更新の途中では実行しないでください。
1つのジョブ、複数のドメイン
すべてのドメインを1つのリストにまとめ、1回のパスでスコアリングを実行します。bulk_dr呼び出しは1クレジットで最大2,000ドメインを処理できるため、1,500件の見込み客リストは10件のリストと同じコストで済みます。ドメインがrefdomainsなどの詳細データが必要な場合にのみ作業を分割してください。
リストを1つの場所に保持してください。ドメインリストのコピーが2つあると、それらは乖離し、トレンドが異なるサイトのセットを比較するようになります。
ジョブを誰が所有すべきか
ジョブには必ず単一のオーナーを割り当てます。共有サーバー上で実行される場合でも構いません。アラートが発生した際に回答し、残高を確認し、失敗した月の再実行が必要かどうかを判断する人物が必要です。オーナーがいない場合、静かに失敗したジョブが四半期にわたって見逃される可能性があります。ログのヘッダーにオーナーの名明を記載し、次の担当者が誰に問い合わせればよいか明確にしてください。
まず小規模なリストでテストする
ジョブを変更する際は、フルリストに適用する前に5つのドメインで実行してください。ループ内のミスは、小規模なサンプルでは数秒で、大規模なリストではクレジットの消費として顕在化します。5ドメインのテストはほぼコストがかかりません。ループの発生を確認するには5ドメインで十分です。
そのテストリストをリポジトリ内のジョブの隣に保管し、確認するたびに同じリストを使用できるようにします。
パイプラインが不適切な場合
パイプラインがその存在価値を発揮するのは、同じデータを繰り返し必要とする場合です。適切なツールを選択してください。単一の質問に対しては、手動でのデータ取得の方が適していることが多いです。実際にどちらが必要なのかを正直に判断してください。
パイプラインをスキップするもう一つの理由は、作業の性質です。質問が毎週変わる場合、固定されたジョブは誤った指標を測定し続けることになります。
単発のエクスポートはパイプラインではない
例えば、単一のピッチのために競合他社の参照ドメインが必要だとします。refdomains を一度実行し、ファイルを保存して次に進みます。そのような用途にスケジュールジョブを作成すると、インサイトは増えずに保守コストだけが増加します。
数値が他のデータと出会うとき
リンクデータは一種類の質問に答えます。キーワードランキング、コンバージョン、通話ログなどと結合する必要がある場合は、結合処理を自前のシステムで行い、リンクスナップショットを一つの入力として保持してください。API に他のソースを保持させることは期待しないでください。
何を、どの期間保持するかを決定する
最初の実行前に、どのフィールドを保存し、自前でどの期間保持するかを決定してください。不要な行は削除してください。ファイルが小さいほど、クライアントや同僚と共有しやすく、プロジェクト終了時に削除もしやすくなります。
エンドポイントリファレンス にはすべてのフィールドと各呼び出しのコストが記載されており、この決定を文書化しやすくなります。
プリフライトリスト
- キーはシークレットとして保存し、リポジトリには含めない。
- ループは希望ではなく行数に基づいて終了する。
- HTTP 401 と 402 は個別に処理する。
- スナップショットには日付を付与し、保持する。
- テーブルごとにスコアベンダーは1つ。
- 毎時ではなく毎月スケジュール。