3.4要件に応じたコード構築

ここまでで各プラットフォームの守備範囲とモデル駆動の手法を押さえました。この節では総合編として、具体的な要件を1本のコードに落とす判断を扱います。「デバイス一覧が欲しい」「チャットに通知したい」「無線クライアントの一覧が要る」——それぞれどのプラットフォームの・どのエンドポイントを・どのHTTPメソッドで・どんな認証で叩くかを組み立てられることが目標です。さらに実務では他人の書いた（あるいはAIが生成した）スクリプトのどこが間違っているかを見抜く力も問われます。

3.4.1典型タスクとエンドポイントの対応

• デバイス一覧の取得＝企業アクセス網ならCatalyst CenterのIntent API（GET /dna/intent/api/v1/network-device、トークンX-Auth-Tokenが必要）、クラウド管理網ならMeraki（GET /organizations/{orgId}/devices、X-Cisco-Meraki-API-Key）。取得はGETが基本。
• Webexへのメッセージ投稿＝POST /v1/messages に{"roomId": "...", "text": "..."}を送る。新規作成なのでPOST、認証はBearerトークン。クライアント一覧の取得＝MerakiのGET /networks/{networkId}/clientsで、あるネットワークに接続中のクライアントを列挙する。
• 組み立ての定石は「動詞→HTTPメソッド」の対応：取得=GET／作成・送信=POST／置換=PUT／部分更新=PATCH／削除=DELETE。要件の動詞（一覧を"取る"/メッセージを"送る"）が、そのままメソッド選択の手掛かりになる。

3.4.2構築と診断のチェックリスト

• 構築手順＝(1)API docsで正しいエンドポイントとメソッドを確認、(2)認証を用意（MerakiはX-Cisco-Meraki-API-Key、Catalyst Centerは事前にPOST /tokenで得たX-Auth-Token、WebexはBearer）、(3)requestsで呼びresp.status_codeとresp.json()を確認、(4)ページネーション/レート制限に対処。認証ヘッダの付け忘れは401、エンドポイント/メソッド誤りは404/405として現れる。
• 診断の勘所＝応答コードから逆算する。401/403＝認証/権限（キーやトークン、ヘッダ名を疑う）、404＝エンドポイント（URLやID）誤り、405＝メソッド不一致（一覧取得にPOSTを使う等）、429＝レート超過（バックオフ/Retry-After）。他人のコードのバグも、まず返ってきたステータスコードを手掛かりに切り分ける。

あなたはNOCの自動化として「Merakiで管理する店舗ネットワークの接続中クライアント一覧を取得し、台数を毎時Webexスペースに通知する」スクリプトのレビューを頼まれました。同僚のコードはこうです。まずクライアント取得部分で requests.post("https://api.meraki.com/api/v1/networks/L_123/clients") と書かれており、実行すると405 Method Not Allowedが返ります。原因は明確で、一覧の取得はGETであるべきなのにPOSTを使っているメソッド不一致です（requests.get(...)が正しい）。次にヘッダを見るとheaders={"Authorization": "Bearer abc..."}とあり、これはWebexの流儀の付け方で、MerakiはX-Cisco-Meraki-API-KeyヘッダでAPIキーを渡す必要があります——このままだと401 Unauthorizedになります。仮にメソッドと認証を直しても、networkのIDが実在しなければ404、レート制限に当たれば429が返るので、resp.status_codeを見て分岐し、429ならRetry-Afterに従って待つ実装にします。後半のWebex通知は requests.post("https://webexapis.com/v1/messages", json={"roomId": room, "text": f"clients={n}"}, headers={"Authorization": f"Bearer {token}"}) で、これは送信＝POST・Bearer認証が要件に合致しており妥当です。ここで重要なのは、二つのAPIは認証ヘッダの流儀が異なる（Meraki=API-Keyヘッダ、Webex=Bearer）ことと、要件の動詞が「取得(GET)」か「送信(POST)」かでメソッドが決まること、そしてバグは想像で直さずステータスコード(405→メソッド、401→認証、404→エンドポイント/ID、429→レート)から逆算することです。同僚の一見動きそうなコードでも、これらの軸で読めば「なぜ405か・なぜ401か」を最短で言い当て、正しいGET＋正しいヘッダへ修正できます。

3.4.3この節のまとめ

• 要件を「どのプラットフォーム・どのエンドポイント・どの動詞→HTTPメソッド」に落とす：デバイス一覧=GET、Webexメッセージ=POST /v1/messages、クライアント一覧=Meraki GET /networks/{id}/clients
• 認証はプラットフォームで流儀が違う：Meraki=API-Keyヘッダ／Catalyst Center=X-Auth-Token／Webex=Bearer。取り違えは401
• 誤りはステータスコードから逆算して診断：401/403=認証・404=エンドポイント/ID・405=メソッド不一致・429=レート超過