Documentação

Alterações no parâmetro de injeção do construtor da API REST do Adobe Commerce - Guia do desenvolvedor do comerciante

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

O Adobe Commerce e o Magento Open Source introduziram alterações na maneira como as APIs REST lidam com a injeção de parâmetros do construtor. Essa atualização fortalece a estrutura da API da Web, garantindo que somente os tipos de dados apropriados sejam usados nas solicitações de API. Este artigo também responde a perguntas relacionadas ao CVE-2025-54236.

Descrição description

Ambientes

Adobe Commerce/Magento Open Source 2.4.4+, 2.4.5+, 2.4.6+, 2.4.7+, 2.4.8++, 2.4.9-alpha3 (todos os tipos de implantação)

Problema

Aprimoramento da validação do tipo de dados da API do Adobe Commerce - Guia do desenvolvedor do comerciante

Visão geral

O Adobe Commerce e o Magento Open Source introduziram alterações na maneira como as APIs REST lidam com a injeção de parâmetros do construtor. Essa atualização fortalece a estrutura da API da Web, garantindo que somente os tipos de dados apropriados sejam usados nas solicitações de API. Este artigo também responde a perguntas relacionadas ao CVE-2025-54236.

Novidades

Segurança de Tipo Aprimorada em APIs da Web

A partir do Adobe Commerce e do Magento Open Source 2.4.4-p16, 2.4.5-p15, 2.4.6-p13, 2.4.7-p8, 2.4.8-p3 e 2.4.9-alpha3, a estrutura da API da Web agora implementa uma validação mais rigorosa do tipo de dados para parâmetros de construtor em solicitações de API. Essa alteração garante que:

✅ Tipos de dados simples (sequências, números inteiros, booleanos) continuam a funcionar perfeitamente.
✅ API As interfaces de dados (Api\Data\*Interface) permanecem com suporte completo.
🚫 Classes de serviço e modelos complexos não são mais instanciados automaticamente das cargas da API.

Detalhes técnicos

O que mudou

O ServiceInputProcessor agora valida os parâmetros do construtor com mais restrição durante o processamento de solicitação de API. O aprimoramento introduz uma camada de validação que verifica os tipos de parâmetros antes de tentar a instanciação do objeto. Especificamente, essa validação ocorre no método getConstructorData() quando o sistema tenta preencher os parâmetros do construtor dos dados de carga da API. Anteriormente, todos os tipos de parâmetros eram processados; agora, somente tipos aprovados são permitidos por meio de. 

Tipos de dados permitidos

SUPORTADO (nenhuma alteração necessária):

Tipos simples

  • string - Valores de texto, nomes de produtos, descrições
  • int / integer - Valores numéricos, quantidades, IDs
  • float / double - Números decimais, preços, pesos
  • bool / boolean - Valores verdadeiros/falsos, sinalizadores de status

Interfaces de Dados de API

  • Todos  *\Api\Data\*Interface classes

Integrações Possivelmente Afetadas

As integrações personalizadas que podem precisar de revisão incluem:

1. Extensões Personalizadas e Módulos de Terceiros

  • Extensões enviando parâmetros de construtor não padrão
  • Módulos que usam injeção de objeto complexo em cargas de API
  • Endpoints de API personalizados com estruturas de parâmetros complexas

2. Testando Scripts

  • Vários scripts de teste com cargas complexas

Resolução resolution

Guia de Migração

Auditoria de Chamadas de API

Fazer inventário das integrações atuais:

  1. Documentação da chamada de API: revise todos os pontos de extremidade de API documentados que seu aplicativo usa.
  2. Verificação do Repositório de Códigos: Pesquise na base de códigos por chamadas de API com objetos aninhados complexos.
  3. Análise de Tráfego de Rede: Monitore cargas de API reais que estão sendo enviadas para a Magento.
  4. Análise de Módulo de Terceiros: Verifique todas as extensões instaladas quanto ao uso da API.

Lista de Verificação de Identificação:

  • Injeção de Parâmetro de Construtor: Procure objetos aninhados em cargas de API.
  • Tipos de Objetos Complexos: Verifique se há referências a serviços ou classes de Modelo.
  • Propriedades Personalizadas: Identifique quaisquer parâmetros de API não padrão.
  • APIs específicas de extensão: Examine as implementações da API do módulo personalizado.

Solução de problemas

Mensagens de erro comuns

Nomes de Campos sem Suporte para > 2.4.6

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

Nomes de Campos sem Suporte para < =2.4.6

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

Quando isso ocorrer:

  • Parâmetros de construtor usando tipos complexos são rejeitados.

Etapas de Depuração 

1. Verifique os logs de API no modo sem desenvolvedor (para < =2.4.6).

  • Localização: var/log/exception.log
  • Filtro: pesquise por ServiceInputProcessor entradas.
  • Análise: procure detalhes de processamento do parâmetro.

2. Testar com 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"}}'

Compatibilidade de Versão

Compatibilidade com versões anteriores

  • Embora as alterações mantenham compatibilidade geral com versões anteriores, alterações importantes podem ocorrer para parâmetros da API REST que são tipos complexos e não implementam as interfaces Api\Data.

APIs existentes

  • Todas as APIs padrão do Magento permanecem inalteradas.
  • Nenhuma mudança radical na funcionalidade principal.

Extensões personalizadas

  • Pode exigir atualizações se estiver usando injeção de construtor complexo.
  • Teste recomendado antes da implantação em produção.
  • Os desenvolvedores de extensão devem atualizar a documentação.

Integrações de terceiros

  • Deve ser cuidadosamente testado.
  • Entre em contato com os fornecedores para obter atualizações de compatibilidade.
  • Monitore a integridade da integração após a atualização.

Perguntas frequentes

P: Preciso atualizar todas as minhas integrações de API imediatamente?
R: Somente as integrações que usam a injeção de parâmetro de construtor complexo precisam de atualizações. A maioria das chamadas de API padrão continua funcionando sem alterações. Priorize o teste e a atualização de integrações que usam objetos aninhados complexos em cargas da API.

P: Como posso identificar se minha integração foi afetada?
R: Teste chamadas de API em um ambiente de desenvolvimento com a nova versão.

P: Há alguma ferramenta para migrar automaticamente minhas chamadas de API?
R: Não há uma ferramenta de migração totalmente automatizada. A maioria dos casos envolve a remoção de objetos aninhados complexos e o uso de estruturas de dados de API adequadas.

P: O que acontece com as chamadas de API existentes que usaram injeção complexa?
R: Essas chamadas de API falharão com 400 Solicitação Inválida ou 500 Erro Interno do Servidor (para < =2.4.6).

P: Essa alteração afeta as APIs do GraphQL?
R: Não, esse aprimoramento se aplica somente às solicitações da API REST via ServiceInputProcessor. As APIs do GraphQL não são afetadas.

P: Posso desabilitar temporariamente essa validação para testes?
R: Não, essa validação é incorporada à estrutura principal e não pode ser desativada. Os testes podem ser feitos em versões mais antigas do Magento para verificar o comportamento herdado.

P: O que devo fazer se uma extensão de terceiros for afetada?
R: Entre em contato com o fornecedor para obter uma versão atualizada e compatível. Se não estiver disponível, considere alternativas ou trabalhe com um desenvolvedor para criar uma camada de compatibilidade.

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