JSON-RPCとは？ メッセージ、メソッド、エラーハンドリング

JSON-RPCとは？

JSON-RPCは、メソッドの呼び出し、結果、およびエラーをJSONオブジェクトとして表す軽量な状態レスリモートプロシージャコールプロトコルです。バージョン2.0はメッセージメンバーと処理ルールを定義しますが、HTTPや他の特定のトランスポートを要求しません。クライアントは、メソッド名を指定し、必要に応じて構造化されたパラメータを供給し、レスポンスをリクエストと関連付けるためにIDを使用します。

有用な定義には、メカニズムとその境界の両方が含まれます。JSON-RPCは交換の特定の部分に影響を与えますが、隣接する責任はHTTP、ブラウザ、選択されたトランスポート、アプリケーション、またはサーバーのデータモデルに残ります。それらのレイヤーを分けておくことで、エラーレポートを再現可能にし、構成変更がアクセス制御の決定と誤解されるのを防ぎます。

API開発者にとって、最初の質問は、誰が値や動作を作り出すかということです。次の質問は、誰がそれを解釈するかということです。最後の質問は、どの可観測な結果がその解釈が機能したことを証明するかということです。これらの3つの回答は、用語集の用語をテスト可能なインターフェース契約に変えます。

JSON-RPCメッセージが会話を形成する方法

リクエストオブジェクトには、jsonrpcが2.0に設定され、メソッド文字列、オプションのparams、通常はidが含まれます。Paramsは、位置引数のための配列または名前付き引数のためのオブジェクトであることができます。名前付きパラメータは順序への偶発的な依存を減らしますが、その名前はサーバー契約と正確に一致する必要があります。

成功したレスポンスはリクエストIDを繰り返し、結果メンバーを含みます。失敗したレスポンスはIDを繰り返し、数値コードとメッセージを持つエラーオブジェクトを含むほか、オプションのデータを含みます。結果とエラーは対立するものであり、レスポンスは両方の結果を主張してはいけません。

通知はIDメンバーを省略し、レスポンスを送信せずにサーバーに作業を実行するよう依頼します。レスポンスがないことはプロトコルの一部であるため、通知は成功を確認したり、アプリケーションエラーを送信者に公開したりすることはできません。その不確実性が許容できるときにのみ使用してください。

バッチは、複数のリクエストまたは通知オブジェクトを含むJSON配列です。サーバーはそれらを独自の順序で処理でき、レスポンスの順序はリクエストの順序と一致する必要はありません。したがって、クライアントはバッチ結果をIDによって相関付けます。

JSON-RPC 2.0オブジェクト内のメンバー

以下の用語は、しばしば一つのラベルにまとめられるコンポーネントを区別します。これらは、ネットワークトレースの装飾としてではなく、参加者間のインターフェースとして読むべきです。

なぜJSON-RPCがWebデータ収集で重要なのか

JSON-RPCは、どのバイトが到着するか、どのようにそれらのバイトが解釈されるか、またはブラウザコードが結果を観察できるかを変更できます。収集ワークフローは、ツールを変更する前にその効果を特定する必要があります。要求されたURL、最終URL、レスポンスステータス、表現タイプ、関連するプロトコルフィールド、そして1つの期待されるコンテンツマーカーを記録してください。そのコンパクトな記録は、正しいページをアクセスメッセージ、同意画面、リダイレクトターゲット、空のアプリケーションシェル、または互換性のないエンコーディングから区別します。

直接HTTPは、要求されたデータがオープンサーバーレンダリングレスポンスに存在する場合、最も単純な取得パスです。ブラウザは、承認されたコンテンツがJavaScriptの実行、ブラウザ管理の状態、ナビゲーション、またはブラウザセキュリティポリシーに依存する場合に関連します。これら2つのパスは同じに見えるように強制されるべきではありません：ブラウザは、プラットフォームのルールに従ってクッキー、圧縮、リダイレクト、CORS、およびストレージを管理しますが、直接クライアントは異なるデフォルトのセットを露出します。

セッションの継続性は、あるレスポンスが次のリクエストの状態を確立する場合に重要です。１つの制約のあるクライアントコンテキスト内で、承認されたシーケンスを保持し、必要なロケールとネットワークの起源を保持し、無関係なジョブからの状態を混在させないようにしてください。プロキシはネットワークの起源を変更します; ヘッダーを再現したり、表現をデコードしたり、スクリプトを実行したり、制限されたコンテンツへのアクセスを許可したりしません。

表現の検証が完了してから解析が始まります。最終ホスト、利用可能な場合の正準のID、メディアタイプ、デコード状態、およびフィールドの抽出前に必要なビジネスマーカーを確認してください。この順序は、パーサーがエラードキュメントを技術的に成功した空のレコードに変えるのを防ぎます。

仲介者には明示的な注意が必要です。コンテンツ配信ネットワークはエンコードされたバリアントを選択できますし、ゲートウェイはOPTIONSに応答できます。キャッシュは交渉された応答を再利用できますし、アプリケーションサーバーはクッキーや認証フィールドを設定できます。最終ページ出力とアプリケーションコードだけを比較すると、決定を下した可能性のあるレイヤーをスキップしてしまいます。

Scrapeless Universal Scraping API は、チームが許可された公開コンテンツの管理された取得を必要とする場合に関連します。これにはJavaScriptでレンダリングされたページも含まれます。取得契約は、ターゲット、許可されたフィールド、期待される表現、受け入れマーカー、停止条件を定義する必要があります。製品の能力は、ソース条件、プライバシー審査、またはアプリケーションレベルの検証を置き換えるものではありません。

JSON-RPCが適している場合

JSON-RPCは、具体的な製品の動作、互換性要件、または診断の決定を変更する場合にアーキテクチャに位置を確保します。これらのユースケースは、最初に仕事を説明し、次にプロトコル機能を説明します。

JSON-RPCとRESTスタイルのHTTPおよびgRPCの比較

JSON-RPCはメソッドの呼び出しを中心にAPIを構築し、RESTスタイルのHTTPはリソース、表現、および標準メソッドのセマンティクスを中心に構築しています。gRPCもメソッドをモデル化しますが、スキーマツールチェーンとバイナリ指向のトランスポートスタックを追加します。JSON-RPCはコンパクトなメソッドエンベロープが重要であり、トランスポートが別の選択肢である必要があるときに魅力的です。

比較は、レイヤー境界を保つ場合にのみ有用です。2つのメカニズムが1つのリクエストで共存することができ、1つを置き換えても自動的に他方が置き換わることはありません。選択した動作を入力、観測可能な出力、失敗状態、所有権の観点から文書化します。

JSON-RPCがあいまいな結果を引き起こす間違い

• 重要な書き込みのために通知を使用します。 通知には応答がないため、呼び出し元は検証または実行が失敗したかどうかを知ることができません。
• 位置でバッチ応答を一致させる。 仕様は任意の順序での応答を許可します。各結果をリクエストIDに一致させます。
• 呼び出しがアクティブな間、IDを再利用します。 重複したアクティブIDは、特に持続的な接続を介して相関をあいまいにします。
• HTTPステータスをメソッドの結果として扱う。 JSON-RPCがHTTP上で動作する際、トランスポートのステータスとJSON-RPCの結果は異なるレイヤーを説明します。両方を確認してください。
• メソッドスキーマを暗黙のまま残す。 エンベロープはプロトコルメンバーを定義し、すべてのアプリケーションメソッドの型やルールを定義しません。別のメソッド契約を公開してください。
• 内部例外テキストを返します。 エラーデータは、スタックの詳細や秘密を暴露する可能性があります。失敗を安定した公開コードおよび承認された診断フィールドにマッピングしてください。

ほとんどの失敗は、ライブラリやブラウザが自動的に何をしたかについての仮定を取り除いた後に診断が容易になります。最小限のトレースをキャプチャし、秘密情報を削除し、制御された変数を1つずつ変更します。目標は、返された表現の安定した説明を得ることであり、無関係なヘッダーの微調整のコレクションではありません。

A JSON-RPC レビュー シーケンス

このシーケンスは、ローンチ前のデザインレビューとして、また、動作の変更後の生産診断として機能します。プロトコルの証拠をアプリケーションの結果に結びつけます。

1. すべてのメソッドを一覧化し、そのパラメータが位置引数か名前付き引数かを決定してください。一つのAPI内で慣習を軽率に混ぜないでください。
2. ハンドラーを実装する前に、結果スキーマと各メソッドの公開エラーコードを定義します。
3. アクティブな呼び出しの間で一意であり、すべてのクライアント言語で機能するID生成ルールを選択してください。
4. ログとテストでは、輸送失敗、不正なJSON、無効なJSON-RPCオブジェクト、メソッドエラー、および成功した結果を分けてください。
5. 応答を期待せずに、バッチ内に配置された通知を含む通知をテストします。
6. テストでバッチレスポンスの順序をシャッフルして、クライアントが配列インデックスではなくIDで相関していることを証明します。
7. ドキュメント認証、認可、メッセージサイズ制限、およびトランスポートフレーミングは、JSON-RPC自体がそれらを定義していないためです。

レビューを終了するには、小さな承認されたサンプルと拒否されたサンプルを同じ赤actionルールで保存します。将来の変更は、メモリやスクリーンショットだけでなく、既知のページのアイデンティティ、期待されるフィールド、およびデコードされたコンテンツに対して比較できるようになります。

JSONエンベロープ外のセキュリティ境界

JSON-RPCは呼び出し元の認証、トラフィックの暗号化、メッセージサイズの制限、またはメソッドの認可を行いません。これらのコントロールは、選択されたトランスポートおよびアプリケーションに属します。WebSocketデプロイメント、HTTPデプロイメント、およびローカルストリームは、異なる脅威モデルを持ちながら同じJSON-RPCオブジェクトを使用できます。

メソッド名とパラメーターは信頼できない入力です。メソッドを許可リストに対して検証し、メソッドスキーマに対してパラメーターを検証し、呼び出し元のIDが確立された後に認可を適用します。構文的に正しいJSON-RPCリクエストは、操作を実行するための許可ではありません。

エラーレスポンスは、実装の詳細を明かさずにクライアントが行動できるようにするべきです。安定した公開コード、簡潔なメッセージ、制約のある構造化データは、生の例外よりも監視しやすいです。ログは、完全な機密パラメータオブジェクトをコピーすることなく、内部相関値を保持できます。

JSON-RPCを定義する標準

JSON-RPC 2.0 の仕様 リクエスト、レスポンス、通知、およびバッチを定義します。この主要なソースは、この記事で使用される語彙と境界を固定しますが、実装の動作は選択したクライアントとデプロイメントでまだ観察する必要があります。

JSONデータ交換標準 プロトコルによって運ばれるJSON構文を定義します。この主要なソースは、この記事で使用される語彙と境界を固定しますが、実装の動作は選択されたクライアントと展開で観察する必要があります。

OpenRPC仕様 JSON-RPC APIのための機械可読な記述形式を提供します。この主要なソースは、この記事で使用される語彙と境界を修正しますが、実装の動作は選択されたクライアントとデプロイメントでまだ観察する必要があります。

WebSocketプロトコル は、JSON-RPCメッセージのための1つの永続的な輸送手段です。この主要なソースは、この記事で使用される語彙と境界を固定しますが、実装の動作は選択されたクライアントと展開でまだ観察する必要があります。

JSON-RPCの要点

JSON-RPCは小さなメソッド呼び出しプロトコルであり、完全なAPIプラットフォームではありません。そのシンプルさは、チームがメソッドスキーマ、トランスポートの動作、セキュリティ、およびエンベロープに関する可観測性を明示的に定義することで最も効果的に機能します。

参加者が信号を送信し、受信した参加者がそれを解釈します。仲介者が経路を変更でき、その内容マーカーが成功を証明します。これにより、JSON-RPCは失敗後に付加されるラベルではなく、観察可能なシステムの一部となります。

リファレンス

• Scrapeless Universal Scraping API ドキュメント
• Scrapeless Universal Scraping API 製品概要
• Scrapelessのヘッダー、クッキー、セッション、および表現の検証に関するガイド
• GitHubのScrapeless