설명서

Adobe Commerce REST API 생성자 매개 변수 삽입 변경 사항 - 판매자 개발자 안내서

Last update: Tue Sep 09 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Adobe Commerce 및 Magento Open Source에서는 REST API에서 생성자 매개 변수 삽입을 처리하는 방법에 변경 사항을 도입했습니다. 이 업데이트는 API 요청에 적절한 데이터 유형만 사용하도록 함으로써 웹 API 프레임워크를 강화합니다. 이 문서에서는 CVE-2025-54236과 관련된 질문에도 답변합니다.

설명 description

환경

Adobe Commerce / Magento Open Source 2.4.4+, 2.4.5+, 2.4.6+, 2.4.7+, 2.4.8+, 2.4.9-alpha3(모든 배포 유형)

문제

Adobe Commerce API 데이터 유형 유효성 검사 개선 사항 - 판매자 개발자 안내서

개요

Adobe Commerce 및 Magento Open Source에서는 REST API에서 생성자 매개 변수 삽입을 처리하는 방법에 변경 사항을 도입했습니다. 이 업데이트는 API 요청에 적절한 데이터 유형만 사용하도록 함으로써 웹 API 프레임워크를 강화합니다. 이 문서에서는 CVE-2025-54236과 관련된 질문에도 답변합니다.

새로운 기능

웹 API의 향상된 형식 안전성

이제 Adobe Commerce 및 Magento Open Source 2.4.4-p16, 2.4.5-p15, 2.4.6-p13, 2.4.7-p8, 2.4.8-p3 및 2.4.9-alpha3부터 웹 API 프레임워크는 API 요청의 생성자 매개 변수에 대해 더 엄격한 데이터 유형 유효성 검사를 구현합니다. 이 변경 사항은 다음을 보장합니다.

✅ 단순 데이터 형식(문자열, 정수, 부울)은 계속 원활하게 작동합니다.
✅개의 API 데이터 인터페이스(Api\Data\*Interface)가 완전히 지원됩니다.
🚫 서비스 클래스와 복잡한 모델은 더 이상 API 페이로드에서 자동으로 인스턴스화되지 않습니다.

기술 세부 정보

변경 사항

이제 ServiceInputProcessor 이(가) API 요청을 처리하는 동안 생성자 매개 변수의 유효성을 보다 엄격하게 확인합니다. 개체 인스턴스화를 시도하기 전에 매개 변수 유형을 확인하는 유효성 검사 계층을 개선했습니다. 특히, 이 유효성 검사는 시스템이 API 페이로드 데이터에서 생성자 매개 변수를 채우려고 할 때 getConstructorData() 메서드에서 발생합니다. 이전에는 모든 매개 변수 형식이 처리되었습니다. 이제 승인된 형식만 허용됩니다. 

허용된 데이터 형식

지원(변경 필요 없음):

단순 형식

  • string - 텍스트 값, 제품 이름, 설명
  • int / integer - 숫자 값, 수량, ID
  • float / double - 십진수, 가격, 가중치
  • bool / boolean - True/False 값, 상태 플래그

API 데이터 인터페이스

  • 모두  *\Api\Data\*Interface개 클래스

영향을 받을 수 있는 통합

검토가 필요할 수 있는 사용자 정의 통합에는 다음이 포함됩니다.

1. 사용자 지정 확장 및 타사 모듈

  • 비표준 생성자 매개 변수를 전송하는 확장
  • API 페이로드에서 복잡한 오브젝트 삽입을 사용하는 모듈
  • 복잡한 매개 변수 구조를 사용하는 사용자 지정 API 엔드포인트

2. 테스트 스크립트

  • 복잡한 페이로드를 사용하는 다양한 테스트 스크립트

해결 방법 resolution

마이그레이션 안내서

API 호출 감사

현재 통합 인벤토리:

  1. API 호출 설명서: 응용 프로그램에서 사용하는 문서화된 모든 API 끝점을 검토하십시오.
  2. 코드 리포지토리 검색: 복잡한 중첩 개체를 사용하여 코드 베이스에서 API 호출을 검색합니다.
  3. 네트워크 트래픽 분석: Magento으로 전송되는 실제 API 페이로드를 모니터링합니다.
  4. 타사 모듈 검토: 설치된 모든 확장에서 API 사용을 확인하십시오.

식별 검사 목록:

  • 생성자 매개 변수 삽입: API 페이로드에서 중첩된 개체를 찾습니다.
  • 복합 개체 형식: 모델 클래스 또는 서비스에 대한 참조를 확인합니다.
  • 사용자 지정 속성: 비표준 API 매개 변수를 식별합니다.
  • 확장별 API: 사용자 지정 모듈 API 구현을 검토하십시오.

문제 해결

일반적인 오류 메시지

> 2.4.6 에 지원되지 않는 필드 이름

{ "message": "\"{fieldName}\" is not supported. Correct the field name and try again." }

< =2.4.6 에 지원되지 않는 필드 이름

{ "message": "Property \"{fieldName}\" does not have accessor method \"{methodName}\" in class \"{className}\"." }

이 경우:

  • 복합 형식을 사용하는 생성자 매개 변수는 거부됩니다.

디버깅 단계 

1. 비개발자 모드(< =2.4.6)에서 API 로그를 확인하십시오.

  • 위치: var/log/exception.log
  • 필터: ServiceInputProcessor개 항목을 검색합니다.
  • 분석: 매개 변수 처리 세부 사항을 찾습니다.

2. Postman/cURL로 테스트합니다.

# Test individual API calls curl -X POST "https://your-magento-site.com/rest/V1/products" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{"product":{"sku":"TEST","name":"Test Product"}}'

버전 호환성

이전 버전과의 호환성

  • 변경 사항은 전반적인 이전 버전과의 호환성을 유지하지만 복잡한 유형이며 Api\Data 인터페이스를 구현하지 않는 REST API 매개 변수에 대해서는 새로운 변경 사항이 발생할 수 있습니다.

기존 API

  • 모든 표준 Magento API는 변경되지 않습니다.
  • 핵심 기능에 대한 새로운 변경 사항 없음.

사용자 지정 확장

  • 복잡한 생성자 삽입을 사용하는 경우 업데이트가 필요할 수 있습니다.
  • 프로덕션 배포 전에 테스트를 권장합니다.
  • 확장 개발자는 설명서를 업데이트해야 합니다.

타사 통합

  • 철저하게 검사해야 합니다.
  • 호환성 업데이트는 공급업체에 문의하십시오.
  • 업그레이드 후 통합 상태를 모니터링합니다.

FAQ

Q: 모든 API 통합을 즉시 업데이트해야 합니까?
A: 복잡한 생성자 매개 변수 삽입을 사용하는 통합만 업데이트해야 합니다. 대부분의 표준 API 호출은 변경 없이 계속 작동합니다. API 페이로드에서 복잡한 중첩 개체를 사용하는 통합 테스트 및 업데이트의 우선 순위를 지정합니다.

Q: 내 통합이 영향을 받는지 어떻게 식별할 수 있습니까?
A: 새 버전으로 개발 환경에서 API 호출을 테스트합니다.

Q: 내 API 호출을 자동으로 마이그레이션하는 도구가 있습니까?
A: 완전히 자동화된 마이그레이션 도구는 없습니다. 대부분의 경우 복잡한 중첩된 오브젝트를 제거하고 적절한 API 데이터 구조를 사용하는 작업이 포함됩니다.

Q: 복잡한 삽입을 사용한 기존 API 호출은 어떻게 됩니까?
A: 이러한 API 호출은 400 잘못된 요청 또는 500 내부 서버 오류(< =2.4.6)와 함께 실패합니다.

Q: 이 변경 사항이 GraphQL API에 영향을 줍니까?
A: 아니요. 이 개선 사항은 ServiceInputProcessor을(를) 통한 REST API 요청에만 적용됩니다. GraphQL API는 영향을 받지 않습니다.

Q: 테스트를 위해 이 유효성 검사를 일시적으로 비활성화할 수 있습니까?
A: 아니요. 이 유효성 검사는 핵심 프레임워크에 빌드되므로 비활성화할 수 없습니다. 이전 Magento 버전에서 테스트를 수행하여 이전 동작을 확인할 수 있습니다.

Q: 타사 확장이 영향을 받는 경우 어떻게 해야 합니까?
A: 업데이트되고 호환되는 버전에 대해서는 공급업체에 문의하십시오. 사용할 수 없는 경우 대안을 고려하거나 개발자와 협력하여 호환성 레이어를 만듭니다.

recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f