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

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

Como cliente atual do Apigee Edge, você pode migrar sua instalação para o Apigee X para aproveitar novos recursos ou diferentes disponibilidades regionais.

Esta página descreve antipadrões na configuração que você precisa resolver antes de migrar para o Apigee X, além de outras mudanças no comportamento que você precisa conhecer antes da migração.

A lista mais ampla de antipadrões do Apigee Edge descreve práticas de uso que devem ser evitadas em qualquer caso. Esta página descreve as práticas de uso desaconselhadas específicas que vão bloquear 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 estejam 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 fornecer 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 todas as credenciais do 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 o acesso de cada app a todos os produtos de API. Isso será equivalente ao que é possível no 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 do app precisa ter acesso. Você pode 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 validade.

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

Apigee Edge Apigee X
Oferece suporte à criação, atualização e exclusão de descritores de recursos de cache. Não oferece suporte à criação, atualização ou exclusão de descritores de recursos de cache.
Não

Resolução: cache sem tempo de expiração

Defina um tempo de expiração para todos os caches.

Expressões de filtro JSONPath em caminhos indefinidos

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

Para caminhos não definitivos, a consulta do 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 nessa 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 indefinidos

Encontre 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. A Apigee X retorna um erro PathNotFoundException quando o caminho não é encontrado.

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

Ao navegar nessa estrutura de exemplo,

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

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

Apigee Edge Apigee X
Saídas null Saída de erro PathNotFoundException
Sim

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

Encontre e substitua as consultas afetadas.

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

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

As expressões JSONPath com um índice de matriz ou fatias retornam um objeto de matriz no Apigee X.

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

Ao navegar nessa 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 retorna um objeto de matriz

Encontrar e substituir 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 chaveiro do Apigee X só podem conter letras, números e hifens. Os nomes de keystore do Edge não impõem essas restrições.

Não

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

Verifique os nomes do keystore e atualize-os para remover caracteres não compatí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 oferece suporte ao deployment 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, independentemente do caminho base.

Mensagens HTTP que não estão em compliance

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

Os clientes ou o proxy da 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 e assim por diante.

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 ilegais foram encontrados no cabeçalho especificado. Nomes de cabeçalho válidos são compostos de letras em inglês, dígitos e hifens.
MISSING_COLON Falta um : (dois-pontos) no par de 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 Não é permitido um corpo de mensagem com os métodos "GET", "DELETE", "TRACE", "OPTIONS" e "HEAD".
UNSUPPORTED_HTTP_VERSION Uma versão HTTP diferente da 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 nulo ("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 de resposta.
Sim, possivelmente.

Resolução: mensagens HTTP incompatíveis

Corrija todos os erros nos protocolos HTTP antes de migrar para o Apigee X. Se um erro for originado de um aplicativo cliente, peça ao desenvolvedor do app cliente para corrigir o problema.

O tempo de expiração do token OAuth 2.0 é inválido.

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

Os limites de validade 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 do OAuth 2.0, mas a aplicação está planejada. Consulte as diretrizes na seção OAuth da página "Limites". Você precisa definir um token de acesso e um tempo de expiração do token de atualização para o 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: 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>.

Limites de produtos excedidos

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

A configuração do Apigee Edge não é compatível com os limites do produto definidos. Alguns limites de produtos que são documentados, mas não aplicados no Apigee Edge, são aplicados no Apigee X.

Não

Solução: limites de produtos excedidos

Corrija qualquer uso que exceda os limites do produto 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 vai interromper o processamento se encontrar uma <LocalTargetConnection> com as duas configurações.

Não

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

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

Restrições de nome do servidor de destino

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

Os nomes dos servidores de destino do Apigee X só podem conter letras, números, hifens e pontos. Os nomes de servidor de destino de borda 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 custo financeiro" 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 "padrão" para oferecer suporte a um nome de domínio do tipo 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 do Apigee do formulário 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 de maneira adequada.
Sim

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

Você precisa configurar seu próprio domínio e provisionar os certificados de forma adequada.

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 vai ser resolvido com um código de resposta 4xx. Se a resolução 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.