이 페이지는 AI로 자동 번역되었으며 부정확한 내용이 포함될 수 있습니다. 번역 오류를 신고하려면 페이지 오른쪽 목차 아래에 있는 피드백 기능을 사용하세요.

OpenAPI 스키마를 사용한 요청 유효성 검사

이 참조 문서에서는 OpenAPI 스키마가 무엇인지, 어떻게 작동하는지, 그리고 Braze REST API 엔드포인트로 보내는 요청이 올바르게 구성되었는지 전송 전에 확인하는 방법을 설명합니다.

모든 Braze REST API 엔드포인트 페이지에는 OpenAPI 사양에서 생성된 인터랙티브 참조가 표시됩니다. 각 사양에는 스키마가 포함되어 있습니다. 스키마는 엔드포인트가 수락하고 반환하는 데이터에 대한 정확하고 기계가 읽을 수 있는 설명입니다. 이 스키마를 사용하여 요청의 유효성을 검사할 수 있으므로, 실패한 API 호출로 인해 문제를 발견하는 대신 자체 도구에서 구조적 실수를 미리 포착할 수 있습니다.

Braze가 이러한 사양을 게시하는 방법과 해당 사양이 지원하는 다른 워크플로에 대한 전반적인 개요는 Braze OpenAPI 사양 사용하기를 참조하세요.

OpenAPI 스키마란

스키마는 엔드포인트 데이터에 대한 계약입니다. OpenAPI 문서에서 스키마 객체는 엔드포인트가 사용하는 각 필드를 정의하며, 필드 이름, 데이터 유형, 필수 여부, 허용되는 값, 중첩된 객체 및 배열의 구조를 포함합니다.

OpenAPI 스키마는 JSON 데이터의 형태를 설명하기 위해 널리 채택된 표준인 JSON Schema를 기반으로 합니다. 계약이 표준적이고 기계가 읽을 수 있는 형식으로 표현되므로, 필드를 수동으로 확인하는 대신 기성 도구를 사용하여 페이로드를 검증할 수 있습니다. 관련 개념에 대해 더 알아보려면 Learn OpenAPI와 Understanding JSON Schema를 참조하세요.

스키마의 작동 원리

스키마는 적은 수의 기본 구성 요소를 사용하여 데이터를 설명합니다. 가장 일반적인 것은 다음과 같습니다:

유형. string, integer, number, boolean, array 또는 object와 같은 값의 데이터 유형입니다. Swagger 설명서의 Data types를 참조하세요.
필수 필드. 데이터가 유효하려면 반드시 존재해야 하는 속성의 목록입니다.
제약 조건. 허용되는 값의 열거형(enum), format(예: date-time), 문자열 패턴, 최솟값 및 최댓값 등 값을 제한하는 규칙입니다.
중첩 구조. 객체는 다른 객체를 포함할 수 있으며, 배열은 포함하는 항목의 스키마를 선언하므로 스키마는 깊이 구조화된 페이로드를 설명할 수 있습니다.

유효성 검사기는 이러한 규칙을 읽고 데이터와 비교합니다. 필수 필드가 누락되었거나, 값의 유형이 잘못되었거나, 값이 허용된 범위를 벗어난 경우, 유효성 검사기가 구체적인 문제를 보고합니다. JSON Schema 사양에서 이 유효성 검사 동작에 대해 자세히 정의하고 있습니다.

스키마가 유효한 요청을 정의하는 방법

요청 본문을 허용하는 엔드포인트의 경우, 사양의 요청 본문 스키마가 유효한 페이로드의 정확한 형태를 설명합니다. 많은 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 제약 조건을 위반하는 값을 전송합니다.

스키마를 먼저 읽으면, 단 하나의 호출을 하기 전에 어떤 필드를 전송해야 하는지, 각 값이 어떤 유형이어야 하는지, 어떤 값이 허용되는지를 알 수 있습니다.

스키마에 대한 요청 유효성 검사

엔드포인트의 스키마에 대해 페이로드의 유효성을 검사하려면 다음과 같이 합니다.

원하는 엔드포인트의 사양을 다운로드합니다. 각 사양은 https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml 형식의 안정적인 공개 URL에서 사용할 수 있습니다.
사양에서 요청 본문 스키마를 추출합니다.
JavaScript용 Ajv 또는 사용 중인 언어에 맞는 JSON Schema tools 목록의 다른 라이브러리와 같은 JSON Schema 유효성 검사기를 사용하여 해당 스키마에 대해 페이로드의 유효성을 검사합니다.
유효성 검사기가 누락, 유형 오류 또는 범위 초과로 표시한 필드를 수정한 후 요청을 전송합니다.

Spectral과 같은 도구를 사용하여 전체 사양을 린트하고 검증하거나, OpenAPI Generator를 사용하여 타입이 지정된 요청 모델을 생성하여 코드가 구조적으로 유효한 페이로드를 생성하도록 할 수도 있습니다. 이러한 사양을 사용하는 단계별 워크플로는 스키마 사용 방법을 참조하세요.

스키마 유효성 검사가 중요한 이유

스키마에 대해 요청의 유효성을 검사하면 다음과 같은 이점이 있습니다:

오류를 더 일찍 포착합니다. 거부된 API 호출이 아닌 자체 환경에서 누락되거나 잘못 입력된 필드를 찾을 수 있습니다.
실패한 호출을 줄입니다. 처음부터 올바른 형식의 요청을 전송하여 재시도와 문제 해결을 줄입니다.
자신감을 갖고 통합합니다. 요청 형태를 수동으로 복사하는 대신 하나의 기계가 읽을 수 있는 계약에 의존합니다.
검사를 자동화합니다. 테스트 또는 CI 파이프라인에 유효성 검사를 추가하여 코드가 변경되어도 통합이 올바르게 유지되도록 합니다.

Braze 설명서:

외부 참조:

New Stuff!