YAMLとは？構文、データ型、用途、及び落とし穴

Scrapeless Scraping APIは、JSONまたはCSV形式の構造化されたウェブデータを返し、制御されたパイプラインは人間が編集した設定境界が必要な場合にそれをYAMLに変換できます。

YAMLとは何ですか？

YAMLは「YAML Ain't Markup Language」の略です。これは、一般的なプログラミング構造にきれいに対応するように設計されたUnicodeベースのデータシリアライズ言語です。YAMLドキュメントは、キーと値の関連付けのためのマッピング、順序付きコレクションのためのシーケンス、および個々の値のためのスカラーという3つの主要なノードタイプから構成されます。

申し訳ありませんが、そのテキストには翻訳すべき内容がありません。提供する内容を教えてください。 YAML 1.2.2仕様 表現モデル、シリアル化ツリー、プレゼンテーションストリーム、構文、タグ、およびスキーマについて説明します。YAMLのプレゼンテーション層は、同等のデータを書くためのいくつかの方法を提供しており、これにより人間の著者には便利ですが、実装者にはJSONの小さな文法よりも多くの選択肢を提供します。

YAMLはデータであり、定義上は命令言語ではありません。アプリケーションは、デプロイメント、ビルドシステム、自動化ジョブ、静的サイトのメタデータ、およびローカル開発ツールの構成に頻繁に使用します。アプリケーションは、どのキーが有効であるか、そしてそれらのキーが何をするかを決定します。

基本的なYAML構文

YAML構成は、マッピング、シーケンス、数値、ブール値、ネストされた値を組み合わせることができます：

service:
  name: catalog-worker
  enabled: true
  workers: 4
  regions:
    - us-east
    - eu-west
  output:
    format: json
    include_metadata: true

コロンはマッピングキーとその値を区切ります。ダッシュはブロックスタイルでシーケンス項目を導入します。インデントは配置します name, enabled、残りの設定は以下の通りです。 serviceドキュメントにはこのスタイルで波かっことカンマは必要ありません。

マッピング

マッピングは、キーを値に関連付けます。キーは一般的にプレーンな文字列ですが、言語モデルはより複雑なキーも許可します。設定の著者は、アプリケーションライブラリや検証ツールがそれらを予測可能に処理するため、シンプルでユニークな文字列キーを好むべきです。

重複したマッピングキーはポータビリティの問題です。ライブラリはそれらを拒否したり、1つの値を保持したり、オプションによって制御される動作を公開したりする可能性があります。プロダクション構成ローダーは重複を拒否すべきであり、レビュアーと実行中のアプリケーションが同じ有効な設定を確認できるようにすべきです。

シーケンス

シーケンスは順序付けられています。ブロックスタイルは各アイテムにつき1つのダッシュを使用し、フロースタイルはブラケットを使用します：

regions: [us-east, eu-west]

checks:
  - name: schema
    required: true
  - name: links
    required: true

各項目はスカラー、マッピング、または別のシーケンスである可能性があります。順序は、アプリケーション契約が意味を割り当てる場合にのみ使用されるべきです。

スカラーと引用

スカラーには、文字列、数値、ブーリアン、null、特定のスキーマの下のタイムスタンプおよび明示的なタグを持つ値が含まれます。プレーンスカラーは引用符を省略しますが、句読点や特定の単語はYAMLのバージョンやパーサーのスキーマによって予期しない方法で解釈される場合があります。テキストの形式が正確でなければならない場合、値を引用符で囲みます。これには、バージョン番号、先頭にゼロがある識別子、およびブーリアンやnullに似た文字列が含まれます。

シングルクォートの文字列はほとんどの文字をリテラルとして扱います。ダブルクォートの文字列はエスケープシーケンスをサポートします。ブロックスカラーは使用します | ルール: 1. 出力は翻訳されたテキストのみ — 説明は不要、追加のコードフェンスも不要。 2. Markdown/HTMLの構造を正確に保持する（見出し、リスト、リンク、テーブル）。 3. @@CODEBLOCK_0@@ や @@INLINECODE_0@@ のようなプレースホルダートークンは、そのままにする; 決して翻訳、再配置、マージ、またはフォーマットを変更しない。 4. ```コードフェンス```を追加したり削除したりせず、通常のテキストをコードブロックにラップしない。 > 行をスペースに折り畳むために、追加のインジケーターがインデントと末尾の改行を制御します。

コメント、アンカー、エイリアス、およびタグ

ハッシュ文字は、引用スカラーの外部にあるコメントを開始します。コメントは、設定が存在する理由をメンテナーが説明できるため、YAMLを構成に魅力的にします。コメントはコアデータモデルではなくプレゼンテーションの一部なので、多くのパーサーはドキュメントを読み込みおよび書き込む際にそれらを破棄します。

アンカーはノードにラベルを付け、エイリアスは他の場所でそのノードを参照します。これにより、繰り返しの設定を減らすことができます：

defaults: &defaults
  timeout_seconds: 30
  output: json

jobs:
  catalog:
    <<: *defaults
    region: us-east

ここに示されたマージキーは広く使用されていますが、マージの動作はすべてのYAML処理パスにおける単純なユニバーサル機能ではありません。選択したライブラリとアプリケーションのサポートを確認してください。過剰なアンカーグラフは、効果的な値が一か所で見えなくなるため、構成のレビューを難しくします。

タグはノードのタイプや解釈を識別します。標準タグは文字列、整数、マッピング、シーケンス、およびその他のコア値をカバーします。一部のライブラリは、言語オブジェクトを構築するアプリケーション固有のタグをサポートしています。信頼できないタグをオブジェクトコンストラクターにロードすることは危険です。期待されるデータ型に構築を制限する安全なローダーを使用してください。

YAMLスキーマとバージョンの違い

YAMLスキーマは、スカラー文字列がタグにどのように解決されるかを決定します。バージョンとスキーマの違いは、構成リポジトリで見つかる多くの驚くべき例を説明します。ある処理モードでブール値として解釈された単語は、別のモードでは文字列のままである場合があります。数値構文やタイムスタンプの処理も異なることがあります。

YAML 1.2は、そのJSONスキーマを調整し、JSONドキュメントが意図された互換性モデルで有効なYAMLになるようにしています。しかし、すべてのYAMLファイルが有効なJSONであるというわけではありません。コメント、引用されていないキー、ブロックコレクション、アンカー、エイリアス、およびタグは、JSON構文の外にあるYAMLの特徴です。

申し訳ありませんが、テキストが不完全なため、翻訳対象の内容が見つかりません。完全な文を提供していただければ、喜んで翻訳いたします。 YAMLメディアタイプの仕様 レジスタ application/yaml そしてthe +yaml 構造化構文サフィックス。ファイル拡張子だけではパーサースキーマやアプリケーション契約を示すことはできません。プロジェクトはパーサーライブラリを固定し、サポートされるYAMLバージョンまたはサブセットを文書化し、ロードされたデータをアプリケーションスキーマに対して検証する必要があります。

YAMLとJSON

一般的なYAMLの使用例

YAMLのセキュリティと信頼性

信頼されていないYAMLは、信頼されない構造化入力として扱うべきです。言語特有のオブジェクトやアプリケーションクラスではなく、通常のデータ値のみを構築する安全なロードモードを使用してください。一般的なリスクは、以下のように説明される広範なカテゴリに属します CWE-502: 信頼されていないデータのデシリアライズ.

入力サイズ、ネスティングの深さ、エイリアス、および集約の展開に制限を設ける。小さなドキュメントは、アンカーバリューを何度も参照することができ、ローダーがはるかに大きなメモリ内構造を作成する原因となります。ライブラリは異なる制御を公開しているため、テストは代表的な制限でデプロイされたパーサーをテストすべきです。

パース後にロードされたデータを検証します。設定ミスが危険な場合には、未知の最上位キーを拒否します。必須フィールド、許容される列挙値、数値範囲、パス制限、設定間の関係を確認してください。検証エラー時に秘密や完全な設定をログに記録しないでください。

一般的なYAMLの間違い

• インデントのためにタブを使用しています。 スペースを好み、エディターの設定とフォーマッターを通じて一つのインデント幅を強制します。
• あいまいなスカラーを引用せずに放置しています。 ブール値、null、数値、またはタイムスタンプに似た識別子やテキストを引用してください。
• 重複キーを許可します。 ローダーまたはリンターを設定してそれらを拒否します。
• コメントがラウンドトリップを生き残ると仮定します。 多くのオブジェクトベースのローダーは、コメントと元のフォーマットを破棄します。
• アンカーとマージを過剰に使用しています。 再利用は繰り返しを減らすことができますが、隠れた効果的な値はレビューやオーバーライドを難しくします。
• スキーマ検証をスキップします。 適切に構成されたドキュメントでも、誤記されているキーや安全でない値が含まれる場合があります。

YAMLの正しい使い方

1. サポートされている小さなサブセットを定義します。 プロジェクトがアンカー、マージキー、カスタムタグ、マルチドキュメントストリーム、およびフロースタイルを許可するかどうかを決定します。
2. パーサーと動作を固定します。 ライブラリ、サポートされているYAMLバージョン、重複キーのポリシー、安全なロードモードを記録します。
3. リンティングとスキーマチェックを追加します。 デプロイ前にそれらを実行して、インデントエラーや未知のキーが早期に失敗するようにします。
4. 秘密はコミットされたYAMLの外に保持します。 アプリケーションの文書化されたメカニズムに従って、環境提供またはシークレットマネージャーの値を参照します。
5. 効果的な構成をレビューします。 継承やマージが存在する場合、秘密の値を露呈せずに最終設定をレンダリングするコマンドを提供します。
6. 境界が変更される場合は、別のフォーマットを使用します。 大規模データセットの公開APIにはJSONを好み、型付き分析形式を使用します。

結論

YAMLは柔軟なシリアル化言語で、その読みやすいブロックスタイルは特に構成に便利です。その便利さは、インデント、スキーマ、タグ、アンカー、エイリアス、重複キー、パーサーオプションが読み込まれた値に影響を与えるため、より大きな解釈の表面を伴います。信頼できるYAMLワークフローは、サポートされる機能セットを狭め、安全なロードを使用し、結果データを検証し、人間に優しい構成を高ボリュームの機械交換から分離します。