このページはAIにより自動翻訳されており、不正確な内容が含まれている可能性があります。翻訳の誤りを報告するには、ページ右側の目次の下にあるフィードバックをご利用ください。

OpenAPIスキーマを使用したリクエストバリデーション

このリファレンス記事では、OpenAPIスキーマとは何か、どのように機能するか、Braze REST APIエンドポイントへのリクエストを送信する前に正しく構造化されていることを確認するための使い方について説明します。

すべてのBraze REST APIエンドポイントページでは、OpenAPI仕様から生成されたインタラクティブなリファレンスが表示されます。各仕様にはスキーマが含まれています。スキーマとは、エンドポイントが受け入れるデータと返すデータを機械可読な形式で正確に記述したものです。このスキーマを使用してリクエストをバリデーションすることで、失敗したAPI呼び出しの結果としてではなく、自分のツール上で構造上のミスを検出できます。

Brazeがこれらの仕様をどのように公開しているか、また仕様がサポートするその他のワークフローの概要については、Braze OpenAPI仕様の使用を参照してください。

OpenAPIスキーマとは

スキーマはエンドポイントのデータに対するコントラクト（規約）です。OpenAPIドキュメントにおいて、Schema Objectは、エンドポイントが使用する各フィールドを定義します。フィールド名、データ型、必須かどうか、許可される値、ネストされたオブジェクトや配列の構造などが含まれます。

OpenAPIスキーマは、JSONデータの構造を記述するために広く採用されている標準規格であるJSON Schemaに基づいています。コントラクトが標準的な機械可読形式で記述されているため、フィールドを手動でチェックする代わりに、既存のツールを使用してペイロードをバリデーションできます。関連する概念の詳細については、Learn OpenAPIおよびUnderstanding JSON Schemaを参照してください。

スキーマの仕組み

スキーマは、少数の構成要素を使用してデータを記述します。最も一般的なものは以下のとおりです。

型。 string、integer、number、boolean、array、objectなどの値のデータ型です。SwaggerドキュメントのData typesを参照してください。
必須フィールド。 データが有効であるために存在する必要があるプロパティのリストです。
制約。 許可される値のenum、format（例：date-time）、文字列パターン、最小値と最大値など、値の範囲を絞るルールです。
ネスト構造。 オブジェクトは他のオブジェクトを含むことができ、配列は保持するアイテムのスキーマを宣言するため、深くネストされたペイロードを記述できます。

バリデーターはこれらのルールを読み取り、データと比較します。必須フィールドが欠落している場合、値の型が間違っている場合、または値が許可された範囲外にある場合、バリデーターは具体的な問題をレポートします。JSON Schema specificationで、このバリデーション動作の詳細が定義されています。

スキーマが有効なリクエストを定義する仕組み

リクエストボディを受け入れるエンドポイントの場合、仕様のリクエストボディスキーマが有効なペイロードの形式を正確に記述します。多くのBrazeエンドポイントは、ユーザー識別子、メッセージングオブジェクト、オーディエンスフィルターなど、同じリクエスト構造を再利用しています。これらの共有構造のフィールドごとのリファレンスについては、オブジェクトとフィルターを参照してください。文字列のexternal_idと整数のpointsを必須とし、pointsが負の値を取れない簡略化されたスキーマを考えてみましょう。

{
  "type": "object",
  "required": ["external_id", "points"],
  "properties": {
    "external_id": { "type": "string" },
    "points": { "type": "integer", "minimum": 0 }
  }
}

このスキーマを満たすペイロードは有効です。

{ "external_id": "user-123", "points": 50 }

以下の各ペイロードは無効であり、バリデーターがその理由を説明します。

{ "points": 50 } は必須のexternal_idフィールドが省略されています。
{ "external_id": "user-123", "points": "50" } はpointsを整数ではなく文字列として送信しています。
{ "external_id": "user-123", "points": -5 } はminimum制約に違反する値を送信しています。

スキーマを事前に確認することで、API呼び出しを1回も行う前に、どのフィールドを送信すべきか、各値がどの型であるべきか、どの値が許可されているかを把握できます。

スキーマに対してリクエストをバリデーションする

エンドポイントのスキーマに対してペイロードをバリデーションするには、以下のステップを実行します。

使用するエンドポイントの仕様をダウンロードします。各仕様はhttps://www.braze.com/docs/assets/api/openapi/{spec_filename}.yamlの形式で、安定した公開URLから利用できます。
仕様からリクエストボディスキーマを抽出します。
Ajv（JavaScript向け）やJSON Schema toolsリストにある他の言語向けライブラリなどのJSON Schemaバリデーターを使用して、ペイロードをスキーマに対してバリデーションします。
バリデーターが欠落、型の不一致、または範囲外と指摘したフィールドを修正してから、リクエストを送信します。

Spectralなどのツールを使用して仕様全体のリントとバリデーションを行ったり、OpenAPI Generatorで型付きリクエストモデルを生成して、コードが設計上有効なペイロードを生成するようにすることもできます。これらの仕様を使用するステップごとのワークフローについては、スキーマの使い方を参照してください。

スキーマバリデーションが重要な理由

スキーマに対してリクエストをバリデーションすることで、以下のメリットがあります。

エラーの早期検出。 拒否されたAPI呼び出しの結果としてではなく、自分の環境で欠落フィールドや型の不一致を発見できます。
失敗した呼び出しの削減。 最初から正しい形式のリクエストを送信することで、リトライやトラブルシューティングを減らせます。
自信を持った統合。 リクエストの形式を手動でコピーする代わりに、単一の機械可読なコントラクトに依拠できます。
チェックの自動化。 テストやCIパイプラインにバリデーションを追加することで、コードの変更に伴う統合の正確性を維持できます。

Brazeドキュメント:

外部リファレンス:

New Stuff!