Antipadrões de migração do Apigee Edge para o Apigee X

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
info

Como cliente do Apigee Edge, você pode migrar sua instalação para o Apigee X para aproveitar novos recursos ou disponibilidade regional diferente.

Nesta página, descrevemos antipadrões na sua configuração que precisam ser abordados antes da migração para o Apigee X, além de outras mudanças de comportamento que você precisa conhecer antes da migração.

A lista mais ampla de antipatterns do Apigee Edge descreve práticas de uso que devem ser evitadas em qualquer caso. Nesta página, descrevemos as práticas de uso não recomendadas específicas que bloqueiam uma migração. Resolva esses problemas agora para evitar problemas ao migrar para o Apigee X.

Apps sem produtos de API

Resumo Requer mudanças no lado do cliente? Resolução

Há apps sem produtos de API.

Diferença entre a Apigee Edge e a Apigee X:

Apigee Edge Apigee X
É possível configurar um app e uma credencial que não estão associados a nenhum produto de API. Esse app tem acesso a todos os produtos de API. Cada app precisa ser configurado para acessar pelo menos um produto de API. Não é possível conceder acesso a todos os produtos de API de forma implícita. É possível configurar um app para ter acesso a todos os produtos de API, mas isso precisa ser feito explicitamente.
Não.

Resolução: apps sem produtos de API

Associe cada credencial de app a pelo menos um produto de API. Para mais informações sobre como fazer isso, consulte Registrar apps e gerenciar chaves de API.

Uma maneira fácil é atribuir a cada app acesso a todos os produtos de API. Isso será o equivalente ao que é possível na Apigee Edge. O desafio será se você quiser seguir uma abordagem de "privilégio mínimo". Nesse caso, será necessário determinar a lista mínima de produtos de API a que cada credencial de app precisa ter acesso. É possível analisar isso com os relatórios do Apigee Edge Analytics, com base no ID do cliente.

Cache sem tempo de expiração

Resumo Requer mudanças no lado do cliente? Resolução

Os caches não têm um tempo de expiração.

Diferença entre a Apigee Edge e a Apigee X:

Apigee Edge Apigee X
Permite a criação, atualização e exclusão de descritores de recursos de cache. Não é compatível com a criação, atualização ou exclusão de descritores de recursos de cache.
Não

Resolução: cache sem prazo de validade

Defina um horário de expiração para todos os caches.

Expressões de filtro JSONPath em caminhos não definitivos

Resumo Requer mudanças no lado do cliente? Resolução

Para caminhos não definitivos, consultar o resultado de uma expressão de filtro não faz parte da especificação JSONPath. Consulte https://goessner.net/articles/JsonPath/.

Diferença entre a Apigee Edge e a Apigee X:

Ao navegar por essa estrutura de exemplo,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

Com a expressão $..books[?(@.name == 'A')][0],

Apigee Edge Apigee X
Saídas ‘{"name": "A"}’ Saídas []

Com a expressão $..books[?(@.name == 'A')][0].name,

Apigee Edge Apigee X
Saídas "A" Saídas []
Sim

Resolução: expressões de filtro JSONPath em caminhos não definitivos

Localize e substitua as consultas afetadas.

Expressões JSONPath para índices que não estão presentes

Resumo Requer mudanças no lado do cliente? Resolução

As expressões JSONPath com um índice que não está presente têm comportamentos diferentes no Apigee X em comparação com o Apigee Edge. O Apigee X retorna um erro PathNotFoundException quando o caminho não é encontrado.

Diferença entre a Apigee Edge e a Apigee X:

Ao navegar por essa estrutura de exemplo,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

Com a expressão $.books[3],

Apigee Edge Apigee X
Saídas null Gera um erro PathNotFoundException
Sim

Resolução: expressões JSONPath para índices que não estão presentes

Localize e substitua as consultas afetadas.

Expressões JSONPath com um índice de matriz que não retornam um objeto de matriz

Resumo Requer mudanças no lado do cliente? Resolução

Expressões JSONPath com um índice ou intervalos de matriz retornam um objeto de matriz no Apigee X.

Diferença entre a Apigee Edge e a Apigee X:

Ao navegar por essa estrutura de exemplo,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

Com a expressão $.books,

Apigee Edge Apigee X
Saídas {“name”:”A”, “name”: “B”} Saídas [{“name”:”A”, “name”: “B”}]

Com a expressão $.books[-1],

Apigee Edge Apigee X
Saídas {“name”: “B”} Saídas [{“name”: “B”}]

Com a expressão $.books[-2:],

Apigee Edge Apigee X
Saídas {“name”:”A”, “name”: “B”} Saídas [{“name”:”A”, “name”: “B”}]
Sim

Resolução: expressões JSONPath com um índice de matriz que não retornam um objeto de matriz

Encontre e substitua expressões que podem retornar resultados diferentes após o upgrade.

Restrições de nome do keystore

Resumo Requer mudanças no lado do cliente? Resolução

Os nomes de keystore do Apigee X só podem conter letras, números e hífens. Os nomes de keystore do Edge não impõem essas restrições.

Não

Resolução: restrições de nome da keystore

Verifique os nomes dos keystores e atualize-os para remover caracteres incompatíveis, se necessário.

Vários caminhos base implantados para um proxy de API

Resumo Requer mudanças no lado do cliente? Resolução

Várias revisões de um proxy de API são implantadas em um ambiente e cada revisão tem um caminho base diferente.

Diferença entre a Apigee Edge e a Apigee X:

Apigee Edge Apigee X
Oferece suporte à implantação de várias revisões de um proxy de API em que cada revisão pode ter um caminho base diferente. Não é compatível com a implantação de várias revisões de um proxy de API mesmo que o proxy tenha caminhos base diferentes.
Não

Resolução: vários caminhos base implantados para um proxy de API

Atualize todos os pacotes para que apenas uma revisão de um pacote seja implantada em um ambiente, independente do basepath.

Mensagens HTTP não compatíveis

Resumo Requer mudanças no lado do cliente? Resolução

Os clientes ou o proxy de API enviam mensagens (solicitações ou respostas) que não estão em conformidade com o padrão HTTP. Por exemplo, nomes de cabeçalho inválidos, duplicações em alguns cabeçalhos restritos etc.

Não é possível migrar para o Apigee X se a execução da API tiver um ou mais dos seguintes erros:

Erro Detalhes
INVALID_CHARACTERS_IN_HEADER Um ou mais caracteres inválidos foram encontrados no cabeçalho especificado. Nomes de cabeçalho válidos são compostos de letras em inglês, dígitos e hífens.
MISSING_COLON Está faltando um : (dois-pontos) no par nome e valor do cabeçalho.
MULTIPLE_CONTENT_LENGTH Vários valores foram fornecidos para o cabeçalho "Content-Length".
CONTENT_LENGTH_NOT_INTEGER O valor do cabeçalho "Content-Length" não é um número inteiro.
INVALID_UPGRADE O cabeçalho "Upgrade" precisa ser usado apenas para ativar conexões WebSocket, mas não é.
URL_HEADER_SIZE_TOO_LONG O tamanho total do URL e dos cabeçalhos da solicitação excede o tamanho máximo permitido de 15 KB.
BODY_NOT_ALLOWED Um corpo de mensagem não é permitido com os métodos "GET", "DELETE", "TRACE", "OPTIONS" e "HEAD".
UNSUPPORTED_HTTP_VERSION Uma versão HTTP diferente de 1.1 está sendo usada para a solicitação e não é compatível.
ZERO_CONTENT_LENGTH_FOR_POST_OR_PUT Um valor de campo de cabeçalho Content-Length zero ("0") foi definido para um método "POST" ou "PUT".
UNSUPPORTED_RESPONSE_PREFIX Um prefixo de cabeçalho "X-Apigee-" sem suporte estava presente no cabeçalho da resposta.
Sim, possivelmente.

Resolução: mensagens HTTP não compatíveis

É necessário corrigir todos os erros nos protocolos HTTP antes de migrar para o Apigee X. Se um erro tiver origem em um aplicativo cliente, peça ao desenvolvedor dele para corrigir o problema.

Tempo de expiração do token OAuth 2.0 inválido

Resumo Requer mudanças no lado do cliente? Resolução

Os limites de expiração do token OAuth 2.0 estão fora do intervalo prescrito.

Diferença entre a Apigee Edge e a Apigee X:

Apigee Edge Apigee X
No momento, não há restrição no tempo de expiração do token OAuth 2.0, mas a aplicação está planejada. Consulte as diretrizes na seção OAuth da página "Limites". Você precisa definir um tempo de expiração para o token de acesso e o token de atualização do OAuth 2.0. Os intervalos aceitos são:
  • 180 segundos <= tempo de expiração do token de acesso do OAuth 2.0 <= 30 dias
  • 1 dia <= prazo de validade do token de atualização do OAuth 2.0 <= 2 anos
Não

Resolução: tempo de expiração do token OAuth 2.0 inválido

Use a política OAuthV2 e especifique o tempo de expiração em <ExpiresIn> e <RefreshTokenExpiresIn>.

Limite de produtos excedido

Resumo Requer mudanças no lado do cliente? Resolução

A configuração do Apigee Edge não está em conformidade com os limites de produto definidos. Alguns limites de produtos documentados, mas não aplicados no Apigee Edge, são aplicados no Apigee X.

Não

Resolução: limites de produtos excedidos

Corrija qualquer uso que exceda os limites de produtos antes de migrar para o Apigee X.

Políticas ServiceCallout com especificadores de conexão de destino de endpoint e caminho

Resumo Requer mudanças no lado do cliente? Resolução

Na política ServiceCallout, o elemento <LocalTargetConnection> precisa incluir os elementos <APIProxy> e <ProxyEndpoint> ou o elemento <Path>, mas não os dois. Para mais informações, consulte o elemento <LocalTargetConnection>.

O Apigee Edge documenta esse requisito, mas não o aplica. A Apigee X interrompe o processamento se encontrar um <LocalTargetConnection> com as duas configurações.

Não

Resolução: políticas ServiceCallout com especificadores de conexão de destino de endpoint e caminho

Verifique as configurações da política ServiceCallout e elimine as configurações <LocalTargetConnection> que não estão em conformidade.

Restrições de nome do servidor de destino

Resumo Requer mudanças no lado do cliente? Resolução

Os nomes de servidores de destino do Apigee X só podem conter letras, números, hífens e pontos. Os nomes de servidores de destino do Edge não impõem essas restrições.

Não

Resolução: restrições de nome do servidor de destino

Verifique os nomes dos servidores de destino e atualize-os para remover caracteres não compatíveis, se necessário.

Certificado de teste em um host virtual

Resumo Requer mudanças no lado do cliente? Resolução

Um ou mais hosts virtuais usam o certificado de "teste sem custos financeiros" fornecido pela Apigee. Isso faz com que o host virtual responda a solicitações em domínios como ORG-ENV.apigee.net.

Diferença entre a Apigee Edge e a Apigee X:

Apigee Edge Apigee X
Configura automaticamente o vhost "default" para oferecer suporte a um nome de domínio do formato ORG-ENV.apigee.net. Há um certificado curinga, conhecido como "certificado de teste sem custo financeiro", que permite o TLS nesses domínios. Os domínios legados da Apigee no formato ORG-ENV.apigee.net não estão disponíveis no Apigee X. Você precisa configurar seu próprio nome de domínio e provisionar certificados adequadamente.
Sim

Resolução: certificado de teste em um host virtual

Você precisa configurar seu próprio domínio e provisionar certificados adequadamente.

Qualquer aplicativo cliente que dependa do nome de domínio legado do formulário ORG-ENV.apigee.net precisa ser modificado para chamar o novo domínio.

DNS não resolvido

Resumo Requer mudanças no lado do cliente? Resolução

Os endpoints de destino têm nomes de domínio não resolvidos.

Diferença entre a Apigee Edge e a Apigee X:

Apigee Edge Apigee X
Se a resolução de DNS falhar, a Apigee vai anexar .apigee.com ao nome de domínio, e o DNS será resolvido com um código de resposta 4xx. Se a resolução de DNS falhar, a Apigee não vai executar a solicitação e vai retornar um código de resposta 5xx.
Não

Resolução: DNS não resolvido

Atualize o endpoint de destino com um nome de domínio válido.