非公開・preview API を相手にする前に「本当に使えるか」を確定する手順

新機能（limited preview / early access）に自動化を賭ける前に、実装より先に「到達可能か」を一次ソースで確定するための手順書。 AI に読ませればそのまま実行できる粒度で書いてある。所要 15〜30分。これを飛ばすと「作ったが使えない」に半日以上を落とす。

この手順が防ぐ失敗

• 「API が無い」と誤って断定して、実は非公開で存在するものを見落とす
• 逆に「あるはず」と仮定して作り込み、提供対象外で動かせない
• AI が学習データに無い preview API を推測で書き、実行時に初めて壊れる
• ユーザーに「設定をオンにして」と頼んだが、その設定項目自体が存在しない

---

手順1: 公開ディスカバリに登録されているか

多くのクラウドベンダーは公開 API の一覧（ディスカバリ）を持つ。Google の場合:

curl -s "https://www.googleapis.com/discovery/v1/apis" -o /tmp/apis.json
grep -oE '"name": "[^"]*"' /tmp/apis.json | grep -iE '<探している機能名>' | sort -u
grep -oE '"id": "[^"]*"' /tmp/apis.json | wc -l   # 総数。取得成功の証拠として必ず出す

ヒットしなければ「公開 API としては未提供」。**ただしこの時点で「存在しない」と書くな。**手順2へ。

手順2: サービスホストの実在を 403 vs 404 で判定する（対照実験が必須）

未登録でも、サービスホスト自体は生きていることがある。必ず架空ホストと並べて比較する。 単独で 403 を見ても「既定の応答」か「実在の印」か区別できない。

for h in "<推定ホスト>.googleapis.com" "<既知の実在API>.googleapis.com" "zzzznotreal999.googleapis.com"; do
  printf "%s  %s\n" "$(curl -s -o /dev/null -w '%{http_code}' "https://$h/\$discovery/rest?version=v1")" "$h"
done

判定表:

応答	意味
404（HTML のエラーページ）	ホストが存在しない
403 PERMISSION_DENIED + Method doesn't allow unregistered callers	ホストは実在。既知の実在 API と文言が一致することを確認する
200	公開されている

さらに API キーを付けて叩くと、エラーの details[].metadata.service にサービス名が返ることがある。 ベンダー自身がサービス名を名乗る＝実在の決定的証拠。

curl -s "https://<推定ホスト>.googleapis.com/\$discovery/rest?version=v1&key=<任意のキー>" | head -c 700

キーが無効でも構わない。API_KEY_INVALID のエラー本文に "service": "<推定ホスト>" が入れば実在。

手順3: 公開リファレンスの有無をパス総当たりで確定する

ドキュメントの URL を推測で1本だけ叩いて 404 を見ても、URL を間違えただけかもしれない。候補を並べて 200 だけ拾う。

for p in "" "/overview" "/quickstart" "/reference/rest" "/guides" "/how-to" "/manifest"; do
  u="<docs のベースURL>$p"
  code=$(curl -s -o /dev/null -w "%{http_code}" -L "$u")
  [ "$code" = "200" ] && echo "200  $u"
done

200 で返るページだけが「公式に文書化された面」。ここに無い操作は仕様が公開されていない。

手順4: ここまでの結論を正しい言葉で書く

**「API が無い」と「非公開で使えない」は別物。**混同すると判断を誤る。

• 手順1 ヒットなし ＋ 手順2 で 403（実在）＋ 手順3 で 404 → 「サービスは実在するが公開ディスカバリ未登録・リファレンス未公開。仕様が公開されていないため実用経路は無い。将来 GA 化される可能性はある」
• 手順2 で 404 → 「そのようなサービスは存在しない」

前者を「無い」と書くと、後で GA 化したときに再調査コストを二重に払う。

手順5: 提供対象かどうかを管理画面で確認する（ここが最頻の落とし穴）

公式ドキュメントに「管理者が設定をオンにする」と書いてあっても、preview 対象外のテナントではその設定項目が存在しない。 ドキュメントの記述を根拠に「オンにしてください」と依頼すると、相手は存在しないスイッチを探して時間を失う。

依頼する前に必ず: 管理画面の該当セクションのスクリーンショットを見せてもらい、項目の有無を目で確認する。 項目が無ければ「設定がオフ」ではなく「提供対象外」が結論。管理 API があるならそちらで読む。

判定文の型:

管理画面 → <パス> に並ぶのは N 項目のみ（<列挙>）。ドキュメントにある <設定名> の項目自体が存在しない。 したがってオンにする操作は成立せず、このテナントは preview 対象外。

手順6: 実装するなら「逐語コード」を AI に渡す

preview API は AI の学習データに無い。プロンプトに「公式に従え」と書くだけでは推測でメソッド名を捏造する。 公式ページからコードブロックを逐語抽出してファイルに落とし、それを唯一の正として渡す。

curl -sL "<公式ページURL>" -o page.html
python - <<'PY'
import re, html
s = open('page.html', encoding='utf-8', errors='replace').read()
out = []
for i, b in enumerate(re.findall(r'<pre[^>]*>(.*?)</pre>', s, re.S), 1):
    t = html.unescape(re.sub(r'<[^>]+>', '', b)).strip()
    if len(t) >= 25:
        out.append(f"----- code block {i} -----\n{t}")
open('REFERENCE.txt', 'w', encoding='utf-8').write('\n\n'.join(out))
print('抽出:', len(out), 'blocks')
PY

指示ファイルに明記する一文:

この機能は limited preview で、お前の学習データには正確な情報が無い可能性が高い。 API 名・関数シグネチャ・戻り値の構成は REFERENCE.txt だけを正とし、記憶や推測で API を書くな。 REFERENCE.txt に載っていない API を呼ぶな。

手順7: 検証しきれない API 呼び出しは「壊れても即原因が分かる形」にする

公式サンプルが一部の型しか示していないことがある（例: 整数出力のサンプルしかなく、文字列版のメソッド名が確認できない）。 実機で確かめられないなら、候補を順に実在判定し、全滅時に実在メソッド名を列挙して投げる。

/**
 * 実在するセッターを選んで値を設定する。
 * preview 中の API 名変更に備え、候補を優先順に判定する。
 */
function setValueDefensively(builder, value) {
  var candidates = ['addStringValue', 'addStringValues', 'setStringValues'];
  for (var i = 0; i < candidates.length; i++) {
    var name = candidates[i];
    if (typeof builder[name] === 'function') {
      return name === 'setStringValues' ? builder[name]([value]) : builder[name](value);
    }
  }
  var found = [];
  for (var k in builder) { if (typeof builder[k] === 'function') found.push(k); }
  throw new Error(
    '値を設定するメソッドが見つかりません。preview のため API 名が変わった可能性があります。\n' +
    '実在するメソッド: ' + found.join(',')
  );
}

これで「xxx is not a function」という手掛かりの無い失敗が、正解のメソッド名が書かれたエラーになる。1回動かせば確定する。

手順8: 契約の食い違いをローカルで潰す（実機に入る前に）

宣言（マニフェスト/スキーマ）と実装の識別子の食い違いが最頻の失敗。実機に入る前に機械で照合する。

// マニフェストで宣言した入出力 ID が実装側に存在するかを突き合わせる
const manifest = JSON.parse(read('<manifest>'));
const code = read('<実装ファイル>');
for (const id of EXPECTED_OUTPUTS) {
  check(code.includes(id), `出力 ${id} が実装側で参照されている`);
}
for (const key of ['onConfigFunction', 'onExecuteFunction']) {
  const fn = manifest...[key];
  check(new RegExp(`function\\s+${fn}\\s*\\(`).test(code), `${key}="${fn}" が実装されている`);
}

あわせて実データのフィクスチャを固定し、論理をローカルで再現して期待値と突き合わせる。 実データを外部ツール経由で取ると Markdown エスケープ（\[ \] など）が混入することがあるので、 フィクスチャ作成時に必ず解除する。これを忘れると「検証は通るのに本番と値が違う」状態になる。

手順9: 撤退ラインを先に決める

preview に申込窓口が無い場合、待つしかない。先に判断基準を決めておく。

• 成果物は捨てない。実装・検証を済ませて置けば、提供開始時に追加作業ゼロで動く
• 今日必要な用途があるなら、公式に使える別経路（例: 送信専用 webhook + 自前エンドポイント）へ切り替える
• ただし別経路が公開エンドポイントの新設を伴うなら、公開範囲は勝手に決めず依頼者の判断を仰ぐ

チェックリスト

• 公開ディスカバリを照合し、総数も出した
• 403/404 を架空ホストと対照して判定した
• ドキュメントパスを総当たりし、200 のページだけを根拠にした
• 「無い」と「非公開」を書き分けた
• 管理画面の項目の有無を目で確認した（ドキュメントの記述だけを根拠にしていない）
• 逐語コードを抽出して AI に渡し、「推測で API を書くな」と明記した
• 検証しきれない呼び出しは実在判定＋列挙エラーにした
• 宣言と実装の識別子をローカルで機械照合した
• 撤退ラインを決めた