はじめに
サポート API は、別の Worker が管理するカタログを必要としています。この実験では、公開 API を用意された内部カタログに接続し、欠落したバインディングを再現して修復します。その後、カタログに公開エンドポイントを設定しないまま、両方のサービスをデプロイします。
自分の Cloudflare 学習用アカウントを使用し、これまでの実験で学んだ認証、設定、デプロイの知識を活用してください。この独立した VM は、Node.js 22.22.0、プロジェクトローカルの Wrangler 4.131.1、合成カタログフィクスチャとともに /home/labex/project/service-binding から開始します。以前の VM やリソースは再利用しません。購入済みドメイン、データベース、有料アップグレードは必要ありません。少量のリクエストは通常のアカウント使用量としてカウントされます。
ターミナルは 1 つ開いたままにしてください。2 つのローカルプロセスを使用し、使い捨ての名前を付けたクラウド Worker を 2 つ作成して接続を確認します。その後、呼び出し元と依存先を削除し、VM を終了する前にログアウトします。
欠落したサービスバインディングを再現する
このステップでは、カタログ依存先を意図的に未設定にした公開 API を作成します。別に用意された Worker が、合成カタログの 2 件のエントリを管理します。現時点では、両方のプロセスはこの VM 内でのみ動作します。
cd /home/labex/project/service-binding
node --version
npx wrangler --version
cat catalog/index.js
Node は v22.22.0、Wrangler は 4.131.1 と表示されるはずです。セットアップによってプロジェクトローカルの依存関係はすでにインストールされています。別のマシンで実行する場合は、このプロジェクトの lockfile を使って npm ci を実行してください。フィクスチャは、公開サービスラベル、2 件のエントリ、リクエストの追跡に使用できる任意の合成 probe クエリ値を返します。データは保存しません。
使い捨てのベース名を 1 つ生成し、2 つのリソース識別子を通常の設定に記録します。WORKER_NAME を使えるように、このターミナルは開いたままにしてください。カタログの main は、カタログ自身の設定ディレクトリを基準にした相対パスです。
WORKER_NAME="labex-binding-$(openssl rand -hex 6)"
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"workers_dev": true,
"preview_urls": false,
"services": []
}
CONFIG
cat > catalog/wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME-catalog",
"main": "index.js",
"compatibility_date": "2026-09-14",
"workers_dev": false,
"preview_urls": false,
"routes": [],
"vars": {"SERVICE_ID": "$WORKER_NAME-catalog"}
}
CONFIG
カタログでは workers.dev とプレビュー URL の両方を無効にし、ルートも設定していません。ローカル開発ではテスト用にループバックポートが公開されますが、これは公開クラウドエンドポイントを作成するものではありません。公開 API の空の services リストが、これから診断する不具合です。
公開ハンドラーを作成します。/health はカタログとは独立して動作します。/catalog は内部呼び出しを行う前に、バインディングが存在することを確認します。catalog.internal は完全修飾されたプレースホルダー URL であり、登録する DNS 名ではありません。env.CATALOG が接続先を選択します。任意のクライアントヘッダーを転送する代わりに、意図したクエリ値だけを使って新しい GET リクエストを作成します。
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname === '/health' && request.method === 'GET') {
return Response.json({status: 'ok'});
}
if (url.pathname !== '/catalog') return Response.json({error: 'not_found'}, {status: 404});
if (request.method !== 'GET') {
return Response.json({error: 'method_not_allowed'}, {status: 405, headers: {Allow: 'GET'}});
}
if (!env.CATALOG) return Response.json({error: 'catalog_binding_missing'}, {status: 503});
// This hostname completes the Request URL. The binding selects the target Worker.
const target = new URL('https://catalog.internal/catalog');
target.searchParams.set('probe', url.searchParams.get('probe') || '');
try {
return await env.CATALOG.fetch(new Request(target, {method: 'GET'}));
} catch {
return Response.json({error: 'catalog_unavailable'}, {status: 502});
}
}
};
JS
用意されたカタログと API を、異なる HTTP ポートと Inspector ポートで、別々のバックグラウンドジョブとして起動します。ログによって起動状況を確認できます。& を付けるとシェルプロンプトが戻ります。
npx wrangler dev --config catalog/wrangler.jsonc --ip 127.0.0.1 --port 8081 --inspector-port 9230 > catalog.log 2>&1 &
npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8080 --inspector-port 9231 > api.log 2>&1 &
cat catalog.log
cat api.log
両方のログに準備完了が表示されるまで、必要に応じて cat を繰り返します。その後、レスポンスを確認します。
curl -i http://127.0.0.1:8081/catalog
curl -i http://127.0.0.1:8080/health
curl -i http://127.0.0.1:8080/catalog
カタログは 200 と 2 件のエントリを返します。ヘルスチェックは 200 と {"status":"ok"} を返します。一方、API のカタログルートは 503 と {"error":"catalog_binding_missing"} を返します。依存先は動作していますが、呼び出し元には依存先へ到達するための設定済み機能がありません。この欠落したバインディングの状態で検証を行ってください。
内部接続を宣言してテストする
このステップでは、API コードを変更せずに設定を修復します。実際に動作しているバックグラウンドジョブを確認し、API プロセスだけを停止します。以下の例では API がジョブ 2 であることを前提にしています。
jobs
kill %2
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"workers_dev": true,
"preview_urls": false,
"services": [{"binding": "CATALOG", "service": "$WORKER_NAME-catalog"}]
}
CONFIG
binding は、env.CATALOG として利用できるプロパティ名です。service は、接続先 Worker に設定した名前と完全に一致している必要があります。どちらか一方のスペルが違う場合は、別の問題になります。プロパティがない場合は明示的な 503 が返り、接続先が利用できない場合は 502、または起動・デプロイエラーになる可能性があります。バインディング呼び出しを、公開 URL への fetch に置き換えないでください。
npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8080 --inspector-port 9231 > api.log 2>&1 &
cat api.log
準備完了を待ち、バインディングテーブルを確認します。Wrangler は名前を使って動作中のカタログを検出し、接続状態を表示します。接続されていない場合は、カタログプロセスと、両方の設定名を確認してから再試行してください。
curl -i "http://127.0.0.1:8080/catalog?probe=local-check"
curl -i -X POST http://127.0.0.1:8080/catalog
curl -i http://127.0.0.1:8080/missing
最初のレスポンスは 200 で、カタログの正確なサービスラベル、両方の項目、probe: local-check を含みます。メソッドチェックは 405、未知のルートは 404 を返します。両方のサーバーを起動した状態で検証してください。公開 API を通して新しい probe を送信し、完全なコントラクトを確認します。
バインディングは設定環境に属します。後で --env preview を使用する場合は、env.preview の下に完全な services 配列を宣言し、意図したデプロイ済み接続先を指定してください。サービスバインディングはトップレベルから継承されません。この実験では名前なしの環境を 1 つ使用し、--env は渡しません。Wrangler environments と HTTP service binding interface を参照してください。
内部サービスと公開 API をデプロイする
このステップでは、同じ接続を自分の学習用アカウントにデプロイします。jobs に表示された実際のローカルジョブを両方停止してください。以下の例では、それらがジョブ 1 と 2 であることを前提にしています。
jobs
kill %1 %2
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
表示されたデバイスリンクを、ログイン済みのブラウザーで開き、現在のコードを入力します。Wrangler の権限と Background Access を確認し、前の実験で説明したとおり、学習用アカウントだけを選択してください。ターミナルの処理が完了するまで待ちます。
npx wrangler whoami --json
loggedIn: true と、実際のアカウント名および ID が表示されることを確認します。アカウントが 1 つだけ表示される場合も確認してください。以下の 2 つのコマンドにある YOUR_ACCOUNT_ID を、同じ ID に置き換えます。生成された元の名前とバインディングはそのままにしてください。
cat > catalog/wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME-catalog",
"main": "index.js",
"compatibility_date": "2026-09-14",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": false,
"preview_urls": false,
"routes": [],
"vars": {"SERVICE_ID": "$WORKER_NAME-catalog"}
}
CONFIG
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"preview_urls": false,
"services": [{"binding": "CATALOG", "service": "$WORKER_NAME-catalog"}]
}
CONFIG
公開 Worker が宣言した依存先をすでに利用できる状態にするため、先に接続先をデプロイします。これは 1 つのアトミックなリリースではなく、独立した 2 つのデプロイです。
npx wrangler deploy --config catalog/wrangler.jsonc
npx wrangler deploy --config wrangler.jsonc
カタログには公開ルートがないはずです。API は自身の workers.dev URL と、CATALOG バインディングを表示します。その API URL を正確にコピーして、下の変数に設定してください。アカウントにすでに存在する workers.dev サブドメインを再利用します。初めてアカウントを使用する場合は、既存のサブドメインを変更せず、Wrangler に表示される利用可能なサブドメインのプロンプトに従ってください。
API_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$API_URL/health"
curl -i "$API_URL/catalog?probe=remote-check"
ヘルスチェックは 200、カタログ結果には probe: remote-check が含まれることを確認します。初回デプロイやホスト名の反映には、短時間の再試行が必要になる場合があります。503 または 502 が続く場合は、バインディング設定と接続先のデプロイを確認してください。
同じ学習用アカウントを Dashboard で開き、Compute → Workers & Pages に移動して、2 つの正確な名前を探します。公開 API の Bindings タブを開きます。図に CATALOG バインディングが表示されます。下の表で、Name（CATALOG）と Value（対応する -catalog Worker）を比較してください。ハンドラーではバインディング名が env.CATALOG になり、値がデプロイ済み依存先を識別します。
表にあるカタログ Worker のリンクをたどり、Domains タブを選択します。上部のパンくずリストの末尾が -catalog になっていることを確認してください。Worker URL の下では、Production と Preview の両方のスイッチがオフになっているはずです。Custom Domains and Routes の下には、以下の画像のようにエントリがないはずです。
画像の名前は例です。自分で生成したサフィックスと、アカウントのサブドメインを使用してください。スイッチが無効になっている場合、表示されたアドレスは有効な公開エントリポイントではありません。上で成功した API リクエストは、サービスバインディングを介してこの Worker に到達しています。この確認は読み取り専用で行ってください。内部呼び出しを動作させるために、公開エンドポイントを有効にしたり、ルートを追加したり、バインディングを複製したりしないでください。検証では、アカウント所有権、デプロイ済みサービスバインディング、エンドポイント設定、新しい probe を使ったリモートレスポンスを個別に確認します。これらのエンドポイントを無効にしても、認証済みのアカウントオペレーターがサービスにバインドしたり変更したりすることは妨げません。これはユーザーログインシステムではありません。
依存先を削除する前に呼び出し元を削除する
このステップでは、認証済みの状態で、使い捨てのクラウド Worker を 2 つ削除します。設定ファイルがリソース一覧の役割を果たします。削除する前に、生成された名前とアカウント ID を確認してください。
cat wrangler.jsonc
cat catalog/wrangler.jsonc
最初に公開呼び出し元を削除し、その後で内部カタログを削除します。これにより、削除済みサービスを参照するデプロイ済み呼び出し元が残ることを防ぎます。各プロンプトで実験用の正確な名前を確認し、y キーを 1 回だけ押してください。
npx wrangler delete --config wrangler.jsonc
npx wrangler delete --config catalog/wrangler.jsonc
Wrangler 4.131.1 では、スクリプト削除後に、古い Workers Sites KV の認証エラーが表示されることがあります。権限を拡大したり、その診断メッセージだけを削除成功の証拠と判断したりしないでください。Workers & Pages を更新し、検証を実行します。認証済みの一覧に、両方の正確な名前が存在しないことを確認してください。ネットワークまたは認証の失敗からは判断できません。その他の Worker、アカウント、既存のサブドメインは保持してください。
Lab VM から接続を解除する
このステップでは、クラウド側の 2 つの削除を確認した後、VM の認証を解除します。
npx wrangler logout
npx wrangler whoami --json
明示的に "loggedIn": false と表示されることを確認します。認証されていない状態でのステータスコマンドは、ゼロ以外の終了コードになる場合があります。重要なのは構造化された結果です。検証を行った後、VM を終了してください。Dashboard のブラウザーログインは別のものであり、次の実験のためにログインしたままでも構いません。VM を終了しても、クラウドリソースの削除やログアウトの代わりにはなりません。
まとめ
呼び出し元のバインディングに登録されていない、動作中の依存先を診断しました。依存先の正確なサービス名を宣言し、env.CATALOG.fetch() を介してリクエストを送信しました。ローカルとデプロイ後の probe で、カタログの識別情報とデータが返ることを確認しました。デプロイ済みの接続を確認し、内部サービスの公開エンドポイントを無効なまま維持した後、依存先より先に呼び出し元を削除し、VM の接続を解除しました。
サービスバインディングを使うと、Worker 間の内部接続を明示的に定義できます。名前付き環境には個別の宣言が必要です。また、ローカル接続だけでは、リモートの所有権やエンドポイント設定を証明できません。
