JSONとは何ですか？

Scrapeless Scraping APIは、機械可読結果を必要とするアプリケーションのために、サポートされているウェブソースから構造化データを返します。

JSONは構造化データを表すためのテキスト形式です。オブジェクトは名前付きの値をグループ化し、配列は値を順序どおりに保持します。この形式はテキストエディタで検査するのに十分小さく、異なる言語のソフトウェアが同じ基本構造を交換するのに十分正確です。その名前はJavaScript Object Notationに由来しますが、JSONはJavaScriptプログラムではなくデータ形式です。

JSONレスポンスは、読者がフィールドの意味を理解している場合にのみ有用です。価格、通貨、在庫がある製品レコードは、ラベルのない数値よりも情報が豊富です。このガイドでは、文法を説明し、JSONがHTTP交換にどう適合するかを示し、構文の有効性を信頼できるデータのより難しい問題から分離します。

JSONがデータを表現する方法

JSONには6つの種類の値があります: オブジェクト、配列、文字列、数値、ブーリアン、そしてnull。 JSONフォーマット仕様 オブジェクトは波括弧で書かれ、名前と値のペアで構成されます。配列は角括弧で書かれ、値の順序付けられたシーケンスを含みます。同じ配列には複数のJSON値タイプを含めることができますが、アプリケーションスキーマによってはより厳密なルールが課されることがあります。

文字列は二重引用符を使用します。文字列内では、引用符、バックスラッシュ、および特定の制御文字をエスケープする必要があります。数値は小数文法を使用し、JSONには無限大や未定義のJavaScript値などの値の組み込み表現はありません。真、偽、およびnullという単語は小文字のリテラルです。パーサーは、単一の末尾のカンマまたは引用符のないプロパティ名のためにドキュメントを拒否することがあります。

例えば、仮想のレスポンスは、文字列のタイトル、数値の価格、ブーリアンのinStock値、およびタグの配列を持つitemという名前のオブジェクトを含むことができます。外側の形状は、どのフィールドが一緒に移動するかを示し; 値は、観察されたものを示します。JSONは、これらのフィールドに通貨、タイムゾーン、またはビジネス定義を規定していません。プロデューサと消費者はまだ、各名前に安定した意味を与える契約を必要とします。

JSONドキュメントが保証できることとできないこと

有効なJSONは、そのテキストが文法に従っていることを証明します。しかし、必須フィールドが存在すること、価格が現在のものであること、またはURLが開いても安全であることを証明するものではありません。パーサーは、処理に対してすべてのフィールドが不正なオブジェクトを受け入れることができます。パースした後は、データをユーザーインターフェースや下流のジョブに供給する前に、期待される形状、値の範囲、および識別子を検証してください。

重複したオブジェクト名は特に厄介です。フォーマットはオブジェクト内の名前を理想的には一意であると説明していますが、パーサーによっては重複を異なる方法で処理することがあります。ある実装では最後の値を保持する一方、別の実装ではエラーを報告することがあります。セキュリティ上の決定がフィールドに依存する場合、その名前の二つの矛盾するコピーがシステムの異なるレイヤーを静かに通過することを許可しないでください。

JSONはネイティブの日付型、バイナリブロブ、またはスキーマ宣言を持っていません。アプリケーションは一般的に、時刻を文字列として、バイナリコンテンツを合意された表現を通じてエンコードしますが、それらはコアフォーマットの上に課せられた慣習です。フィールドの隣にその慣習を文書化してください。そうしないと、2つのクライアントが同じテキストを成功裏にパースしても、異なる解釈をする可能性があります。

APIを通じてJSONが移動する方法

HTTP APIは、リクエストボディ、レスポンスボディ、またはその両方にJSONを置くことができます。Content-Typeフィールドは表現を識別し、受信者が適切なパーサーを選択できるようにします。 HTTPセマンティクス仕様 メッセージのメタデータを転送されるボディから分離します。HTTPの成功ステータスはリクエストの結果について何かを示し、レスポンスボディは返されたリソースまたは結果を説明します。

クライアントは、すべてのボディがJSONであると仮定する前に、レスポンスのステータスと予想されるメディアタイプを確認する必要があります。認証に失敗した場合、ゲートウェイエラー、メンテナンスページは別のフォーマットを返すことがあります。受信したボディが期待される操作に属することを確認した後にのみ解析してください。その後、すべてのサービスが結果をdataというプロパティでラップしていると仮定するのではなく、文書化されたフィールドパスを検査してください。

The Scrapeless Scraping APIの紹介 アクター選択のリクエストと構造化された出力について説明します。これはJSONの具体的な使用例です：アプリケーションは文書化された入力オブジェクトを送信し、アクター固有の結果を読み取ります。異なるアクターは異なるフィールドを持つ可能性があるため、単一のジェネリックパーサーはテキストをデコードできる一方で、製品固有のマッピングは依然としてそれを解釈する必要があります。

オブジェクト、配列、および欠損値

オブジェクトは名前付きプロパティに関する質問に答え、配列はシーケンスに関する質問に答えます。検索結果のリストは、各オブジェクトがタイトルやリンクなどのフィールドを保持する結果オブジェクトの配列として自然に表現されます。周囲の応答オブジェクトもページネーションやメタデータを持つ場合があります。それらのレベルを分離することで、どのフィールドが1つの結果を説明し、どのフィールドが全体のリクエストを説明するかを説明しやすくなります。

欠落したプロパティは、値がnullのプロパティとは異なります。欠落しているとは、プロデューサーがフィールドを省略したことを意味する場合があります。nullは文書に明示的に表示されます。どちらのケースも自動的にゼロまたは空の文字列として扱われるべきではありません。消費アプリケーションが各ケースをどのように処理するかを決定し、その決定を実際のAPI契約に対してテストしてください。

数字も同様の注意が必要です。JSONは数の文法を提供しますが、言語ごとに非常に大きな整数や小数をどのように格納するかは異なります。金額や識別子は、浮動小数点の仮定ではなく、文書化された文字列または十進数の表現が必要な場合があります。 JavaScript JSON インターフェース よく知られたパースおよびシリアライズ操作を示していますが、データモデルは依然としてアプリケーションレベルの決定を必要とします。

実践における JSON の検証とデバッグ

ダッシュボードの表示をスクリーンショットで確認するのではなく、生のレスポンスから始めます。そのステータス、メディアタイプ、完全なボディを確認してください。パースが失敗する場合、最初の構文エラーを特定します：エスケープされていない引用符、不足している閉じ括弧、または末尾のカンマが時には十分です。パースが成功してもアプリケーションがまだ失敗する場合は、アプリケーションが期待するフィールドのパスとタイプを検査します。

単なる存在ではなく、意味に対してチェックを行ってください。結果の配列は存在していても空である可能性があります。それは有効な結果なしの結果であったり、上流のアクセス問題の証拠である場合もあります。URLは文字列であっても無関係なページを指すことがあります。正しいものとエッジケースの応答の少数セットを契約の例として保持し、実際のキャプチャではなく例として明確にラベル付けしてください。

公共のウェブデータを摂取する際は、ワークフローが監査可能である必要がある場合に、元のレコードと観察コンテキストへのリンクを保存してください。 Scrapeless Scraping API は、サポートされたソースから構造化された結果を取得するための一つの方法です。それらの結果を保存するアプリケーションは、依然としてアクター固有のスキーマを検証し、ターゲットごとに異なるフィールドをどのように処理するかを決定する必要があります。

JSON が適切な表現であるとき

JSON は、ウェブサービスとクライアント間で小規模から中規模の構造化レコードを交換するのに適しています。専門的なビューアなしでも読み取ることができ、ほとんどの言語には成熟したパーサーがあります。それにより、設定、APIリクエスト、およびいくつかのシステムを通過する必要がある抽出されたレコードに便利です。可読性は人間が手動で本番ペイロードを編集するべきではないことを意味しません。

表形式のエクスポートには、CSVの方がスプレッドシートには簡単かもしれませんが、ネストされた構造を自然に表現することはありません。HTMLはページの構造とプレゼンテーションを保持しますが、アプリケーションがビジネスフィールドを信頼性高く照会する前に抽出が必要になることが一般的です。バイナリ形式はサイズを減らしたり、高ボリュームの内部トラフィック向けに強固なスキーマを追加することができます。データの形状とそれを消費するシステムに応じて選択してください。

役立つ設計の質問は、消費者が元のページを必要とするか、選択されたレコードを必要とするかということです。消費者がサポートされたアクターから製品タイトルと在庫を必要とする場合、構造化された JSON はパース作業を軽減します。消費者が結果を生み出した正確なマークアップを検査する必要がある場合は、適切なページ表現を保持またはリクエストしてください。関連している Scraper API アクター ガイド は、出力の封筒とフィールドがアクターごとに読み取る必要がある理由を示しています。

結論

JSON は構造化された値を交換するための正確なテキスト文法を提供します。それは信頼できる値を作るビジネスルールを提供しません。期待される形状を定義し、実際の API 応答を検査し、アプリケーションが使用するフィールドを検証してから、パースされたドキュメントを信頼できるレコードとして扱うことが重要です。