起きたこと

Google Classroomのアドオンを開発していて、開発環境での動作確認も済んだので本番用のプロジェクトを作成して動作確認したところ、アドオンからの添付でエラーが発生しました。

code": 404, "message": "Method not found.

調査したこと

状況① 開発環境ではうまくいっており、ソースコード自体は変更していない

前提として、環境変数で設定するOAUthクライアント等の値は正しく本番環境用に設定しています。

リクエストの詳細確認

まずは、添付時にどのようなリクエストを送っているか確認してみます。
APIのリクエストの形式は以下のようになっています。
POST https://classroom.googleapis.com/v1/courses/{courseId}/announcements/{itemId}/addOnAttachments

ここで、courseIdと itemIdはクラスルーム内の課題固有の値であり、アドオンの種類によって変動するものではないため、この値が不正であるということではなさそうです。
クエリパラメータとしてaddOnTokenがありますが、これはアドオンのiframeに渡される識別用のトークンで、この値が不正であるなら403 @InvalidAddOnTokenがレスポンスされるため、この値は問題ないと判断しました。
また、APIのリクエストに必要なスコープが不足していることも考えられますが、その場合は401エラーがレスポンスされるため、それが原因ではなさそうです。

つまるところ、添付が成功するパターンと失敗するパターンでクリティカルなリクエストの違いはなさそうでした。

上記のような状況から、ソースコード自体に問題はなく、GCPのプロジェクトの設定に問題があると推測しました。

状況② 本番公開用と開発用（内部アプリ）の設定の違い

この場合、

OAuthの対象ユーザーが「内部」か「外部」で違う
Google Workspace Marketplace SDKでの「アプリの構成 > アプリの公開設定」での設定値が違う

などの差分があります。そのため、問題の切り分けのために、別の開発用のプロジェクトを作成して確認してみました。
しかし、変わらずエラーが出ています。設定内容を隅々まで確認してみましたが、特に気になる部分はありませんでした。

状況③ 組織の管理コンソールでのAPI許可設定

組織の管理者者アカウントで、管理コンソールの「セキュリティ > アクセスとデータ管理 > APIの制御 > Googleサービス」から、サードパーティーアプリに対しての各GoogleサービスAPIの呼び出しを管理できます。
このリストにアプリが表示されるのはどうやら承認の24～48時間後らしく、プロジェクト作成直後の確認ではうまくいかないものかと思い、48時間経過を待ちました。

48時間後、アプリ一覧に表示され、APIへのアクセスも許可しましたが、状況は変わらずでした。

解決方法

上記のような状況から全く原因が分からず、DeepResearch等を使っても解決に至らなかったので手詰まりでした。
一から状況を見直し、アドオンのサンプルプロジェクトを確認したところ、添付でのAPIリクエストでGoogleの公式ライブラリを用いていたことが分かりました。そのため該当部分を公式のサンプルに合わせる形で修正したところ、うまくいきました。

修正前

$client = new \GuzzleHttp\Client();
// 中略
$client->post($url, [
    'headers' => $headers,
    'json' => $body,
]);

修正後

$service = new \Google\Service\Classroom($client);
$sub = new \Google\Service\Classroom\AddOnAttachment();
// 中略
$service->courses_courseWorkMaterials_addOnAttachments->create(
    $courseId,
    $itemId,
    $sub,
    ['addOnToken' => $addonToken]
);

なぜ修正後になるとうまくいくかは調査しきれていないですが（修正前でもリクエスト自体に問題ないはず・・・）、上記のようにすることで添付がうまく機能するようになりました。

学び

公式のサンプルがあるならそれに倣う
公式のライブラリがあるならそれを使う
ソースコードに間違いはない、というバイアスを捨てる
- ひととおり仮説を検証してみてそれでも原因が分からないなら原点に立ち戻ってソースコードを疑う