プラグインが外部サービスへつながらないとき
通信の許可、接続先、認証情報、実行環境を分けて調べ、必要なアクセスだけを設定します。
目次
外部サービスへ接続できないときは、まずプラグインに通信の許可があり、接続先も許可された一覧に入っているかを確認します。認証用のAPIキーが正しくても、この許可がなければ通信できません。
プラグインは、EmDashへ機能を追加する部品です。このガイドで扱う許可設定は、サイト本体と分けた環境で動くサンドボックス型プラグインが対象です。サイト本体と同じ環境で動くネイティブ型の通信範囲は、導入するコードと、サイトを動かす環境の設定を確認してください。
まず、管理画面で使っているプラグインの名前・版・失敗した操作と、エラーの文を控えます。以下の設定ファイルやコードを調べるのは、プラグインの開発者や保守担当者です。利用者は、この情報を揃えて渡すところから始められます。
調べる場所を4つに分ける
| 見るもの | 確認すること |
|---|---|
| プラグインの宣言 | 外部通信を使うと申告しているか |
| 許可された接続先 | 目的のホスト名が含まれているか |
| 外部サービスの認証 | 正しい認証情報と、その操作の利用権限があるか |
| 実行環境 | サンドボックスを動かす仕組みが用意されているか |
外部サービスの「ユーザー名と鍵」が正しくても、その前段の通信許可で止まっている場合があります。反対に、通信が届いてもサービス側の認証で拒否される場合があります。
通信の宣言と、行き先の一覧を確認する
開発者はコードエディターで、プラグインの開発用フォルダーにあるemdash-plugin.jsoncを開きます。これは、必要な権限などをまとめた設定ファイルで、「マニフェスト」とも呼ばれます。ここで、通信の能力を示すnetwork:requestと、接続先のallowedHostsを確認します。次は架空の接続先を使う抜粋です。
{
"capabilities": ["network:request"],
"allowedHosts": ["api.example.com"]
}**capability(ケイパビリティ)**は、プラグインが使いたい操作の種類です。ホスト名は、この例のapi.example.comという接続先を指します。記事を読む権限があっても、外部への通信が自動的に許可されるわけではありません。
これは完全なプラグイン定義ではないので、既存ファイルを丸ごと置き換えないでください。更新は開発者が行い、権限の宣言と実際の処理を揃えます。利用者は、配布済みのファイルを直接変更せず、開発者へ修正を依頼してください。
プラグインは、用意された通信窓口を使う
サンドボックス側のコードでは、ctx.http.fetch()という窓口を通して通信します。EmDashは、その前に許可先と合うかを確認します。許可にない相手へのリクエストは、外へ出る前に止められます。
api.example.comを許可していても、実際の接続先がuploads.example.comなら同じホストではありません。サービスの案内とログ(処理の結果やエラーの記録)を照合して、必要な行き先を確認します。公式の権限ガイド(別タブで開く)には、ホスト指定と転送時の制限が載っています。
たとえば通信先がhttps://api.example.com/v1/itemsなら、ホスト名はapi.example.comです。https://や後ろの/v1/itemsを含むURL全体とは区別します。
「何でも許可」で直さない
接続先を利用者が自由に指定する用途には、制限の異なる通信権限もあります。しかし、決まったAPIへ接続するプラグインなら、必要なホストを列挙する方法を使います。
権限が増える更新では、インストール時と同様に、何が追加されたかを確認します。「画像の説明を更新する」機能なのに、内容の削除や全ユーザーの取得まで必要なのかも、実装と合わせて見ます。
認証エラーと、実行環境のエラーを分ける
通信先から拒否の応答が戻っているなら、キーの期限、サービス側の権限、利用上限などを調べます。共有するログには、キーや個人情報を含めないようにします。
サンドボックスを実行する仕組み自体が使えない場合は、サンドボックス構成を確認します。実行できるようにするためだけに、同じプラグインをネイティブ型として動かすと、隔離や制限の前提が変わります。
小さな取得で、通るところまで確かめる
修正したプラグインを確認用サイトへ入れ、以前失敗した取得操作を少量のデータで試します。エラーが消えただけでなく、期待した情報が返ったかまで確かめます。通信許可、接続先、認証、戻った内容の順に記録すれば、どこで止まったかを開発者へ伝えられます。
内容を書き換えるプラグインでは、人との同時編集も別に調整します。編集ロックがかかっていても、権限を持つプログラムによる操作がすべて止まるとは限りません。