GraphQLとは何ですか？

Scrapeless Agent Browserは、認証されたウェブワークフローの一部として、GraphQLリクエストを通じてデータをロードするブラウザページを実行できます。

GraphQLは、型スキーマを中心に構築されたAPIのためのクエリ言語および実行モデルです。クライアントは名前付きフィールドを要求し、サーバーはそれらのフィールドを選択に似た結果に解決します。これは、すべてのURLが一つの固定された表現を返すインターフェースとは異なります。この区別は、アプリケーションが異なる画面で異なる詳細レベルの関連データを必要とする場合に役立ちます。

GraphQLは、基盤となるデータの所在を指定せず、スキーマがあるからといってリクエストが安全であるとは限りません。サービスは依然としてリゾルバー、認証、認可、運用制限、およびトランスポート契約を必要とします。このガイドは、スキーマから結果までのリクエストを追跡し、その後、GraphQLが統合を支援する場所または複雑にする場所を検討します。

スキーマはAPI契約です

GraphQLスキーマは、タイプ、フィールド、引数、および操作エントリポイントの名前を付けます。フィールドは、タイプシステムに応じて、スカラー、オブジェクト、リスト、またはヌル可能な値を返すことができます。 公式スキーマガイド これらの宣言がクライアントが何を要求できるかを定義する方法を説明します。クライアントは、クエリにフィールド名を書くことができるからといって、単に任意のデータベースカラムを要求することはできません。

スキーマは関係を可視化します。アイテムタイプはタイトルと販売者フィールドを公開する可能性がありますが、販売者タイプは表示名を公開します。クライアントはスキーマが許可されている場合、1回の操作でタイトルとネストされた販売者名を選択できます。サーバーはそれらの値を取得する方法を決定します。その決定は、データベース、別のサービス、またはキャッシュされた結果を含む可能性があります。

ヌラビリティは契約の一部です。これは、フィールドが有効な応答に存在しない可能性があるかどうかを説明し、基盤となるソースが失敗する理由には触れません。クライアントはスキーマに対して生成およびテストを行うべきですが、アプリケーションエラーやデータの質を処理する必要があります。非ヌル宣言は、信頼できない上流ソースを魔法のように完全にすることはできません。

GraphQLクエリがどのようにその形を得るか

クエリ操作はクエリのルートから始まり、スカラーの葉までフィールドを選択します。 公式クエリガイド クライアントが特定のスキーマから取得したいフィールドを正確に指定することを示しています。引数はデータをフィルタリングまたは識別することができ、変数を使用することでクライアントはクエリテキストとは別に値を提供できます。レスポンスデータは選択されたフィールド構造を反映します。

この選択は、要約のみを必要とする画面のために不要なフィールドを減らすことができます。また、そうでなければ複数のリソースリクエストを必要とする関連フィールドを結合することもできます。どちらの結果も自動ではありません。サーバーは、ネストされたフィールドのために高価な作業を行う可能性がありますし、クライアントは画面に必要以上のリクエストをするかもしれません。フィールド選択は、コスト管理が必要な柔軟性を提供します。

役立つメンタルモデルは明示的な選択肢を持つレストランのメニューですが、その結果はアナロジーよりも厳密です：名前とタイプは実行前にスキーマに対して検証されます。スペルミスのあるフィールドは空のプロパティではなく、検証エラーを生成します。この初期チェックは、開発者が混乱した部分的な結果を解釈する前に契約の不一致を発見するのに役立ちます。

ミューテーション、サブスクリプション、およびトランスポート

クエリはデータを読み取ります。ミューテーションはサーバー側の状態を変更する可能性のある操作を表し、サブスクリプションはサービスがそれをサポートしているときに更新を受け取る方法を表します。これらはGraphQLの操作カテゴリであり、特定のデプロイメントについての保証ではありません。 GraphQL 操作参照 その構文と選択動作を説明します。

多くのGraphQLサービスは、クエリやミューテーションにHTTPを使用しますが、GraphQL言語はHTTPとは異なります。リクエストは文書、変数、および操作名を含むことができ、サービスはその交換をどのように公開するかを決定します。サブスクリプションには、サポートされたストリーミングトランスポートとライフサイクルが必要です。GraphQL言語がそれらを定義しているからといって、サーバーがサブスクリプションをサポートしているとは限りません。

GraphQLのレスポンスにはデータとエラーが含まれる可能性があります。一部のフィールドが解決され、他のフィールドが失敗する場合、部分的なデータが可能です。 公式実行ガイド 選択されたフィールドの背後にあるリゾルバーパスを説明します。アプリケーションコードは、データの存在を完全な成功として扱うのではなく、両方のレスポンス部分を検査する必要があります。展開されたトランスポートのステータスとエラーの慣例も重要です。

GraphQL と REST 指向インターフェースの比較

REST指向のAPIは、一様なインターフェースの下でリソースと表現に基づいてインタラクションを整理します。GraphQLは、クライアントのリクエストをスキーマフィールドと操作に基づいて整理します。どちらのスタイルも、良くも悪くも実装できます。選択は、クライアントがデータを発見する方法、サーバーが作業を制約する方法、キャッシングやバージョン変更がどのように管理されるかに影響しますが、基になるデータが正確であるかどうかを決定するものではありません。

リソースエンドポイントは、多くのクライアントが同じ表現を必要とする場合、キャッシュや理解が簡単です。GraphQLフィールド選択は、クライアントが異なる関連データの組み合わせを必要とする際に役立ちます。異なるクエリ文書が同じエンドポイントをターゲットにできるため、共有HTTPキャッシングはそれほど単純ではありません。チームはしばしば、そのトレードオフを管理するために、操作レベルのコントロールやアプリケーションキャッシュを追加します。

GraphQLは、ページネーション、フィルタリングルール、または認証の必要性を排除するものではありません。多くのネストされたオブジェクトを要求するクエリは、1つのHTTPリクエストであってもコストがかかる可能性があります。意図的に大きいまたは誤った選択肢を含む現実的な操作を通じて、クライアントの体験とサーバーのコストの両方を評価してください。ネットワークの往復だけでなく、基礎的な作業を数えることが重要です。

ブラウザページがGraphQLを使用する理由

モダンなページはHTMLシェルをロードし、その後、可視インターフェイスのための構造化データをリクエストできます。そのネットワークトラフィックには、カードやダッシュボードにフィードするレスポンスフィールドを持つGraphQL操作が含まれているかもしれません。 Scrapelessエージェントブラウザ ページとそのJavaScriptを実行し、レンダリングされた状態をブラウザの自動化を通じて観察可能にします。この エージェントブラウザのドキュメント はそのブラウザ実行の役割をカバーしています。

開発者ツールで観察されたGraphQLリクエストは、必ずしもサポートされているパブリックAPIではありません。それはクッキー、プライベートアカウントデータ、または通知なしで変更があるフロントエンド契約に依存する場合があります。関連する ブラウザネットワーク検査ガイド は、観察と許可を区別します。ドキュメント化されたAPIが存在する場合はそれを優先し、分析をパブリックまたは明示的に許可されたデータに制限してください。

タスクがユーザーが見るものを確認することである場合、レンダリングされたブラウザ出力と基盤となるネットワークデータは異なる質問に答えます。GraphQLのレスポンスには、ページが表示しないフィールドが含まれる場合があります; ページはそれらを変換または省略するかもしれません。使用ケースに必要な表現を決定し、その表現が正しいものである理由を説明できるだけのコンテキストを記録してください。

安全にGraphQLを設計し、消費する

サーバー上で、解決される可能性のある機微なデータのフィールドまたはリソース境界で認可を適用します。スキーマフィールドが存在しているからといって、すべてのユーザーがその値を読むことができるわけではありません。高価な操作は、サーバーがサポートする複雑さ、ページネーション、または深さの制御で制限してください。実際のリゾルバー作業を観察し、コンパクトなクエリが静かに大規模なバックエンド作業に拡張されないようにします。

クライアント上では、クエリドキュメントをそれを使用する画面や操作に近く保ってください。必要なフィールドのみをリクエストし、変数に明示的なタイプを与え、nullable値と部分的なエラーを処理します。スキーマの変更は実際のクライアント操作に対してレビューされるべきです; フィールドを追加することは安全な場合がありますが、確立されたフィールドの意味を変更すると、構文が有効であってもクライアントが壊れる可能性があります。

あなたが運営していないサービスについては、特権のある操作をリバースエンジニアリングするのではなく、その公開ドキュメントを読みます。狭い認可されたクエリをテストし、そのレスポンス構造を検査します。サービスが変更されると、スキーマエラーまたは予期しないnullは契約レビューにつながるべきであり、ブラウザページまたはその内部トラフィックがより広範なデータの権利を与えるという仮定にはならない。

結論

GraphQLは、クライアントが型付きAPIスキーマからフィールドを選択し、それらの選択によって形づくられた結果を受け取ることを可能にします。スキーマは発見性とバリデーションを改善し、サービスは実行コスト、認証、およびデータ品質を所有します。実際のクライアントクエリと実際のサーバー契約を使用してGraphQLを評価してください。