Антишаблоны миграции Apigee Edge на Apigee X

Вы просматриваете документацию Apigee Edge .
Перейти к документации Apigee X. info

Как текущий клиент Apigee Edge, вы можете решить перенести свою установку на Apigee X , чтобы воспользоваться новыми возможностями или другой региональной доступностью.

На этой странице описываются антипаттерны в вашей конфигурации, которые необходимо устранить перед миграцией на Apigee X, а также другие изменения в поведении, о которых следует знать перед миграцией.

Более широкий список антипаттернов Apigee Edge описывает практики использования, которых следует избегать в любом случае. На этой странице описаны конкретные нерекомендуемые практики использования, которые могут помешать миграции. Устраните их сейчас, чтобы предотвратить проблемы при миграции на Apigee X.

Приложения без API-продуктов

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Имеются приложения без API-продукта(ов).

Разница между Apigee Edge и Apigee X:

Апигей Эдж Апигей X
Можно настроить приложение и учётные данные, не связанные ни с одним продуктом API. Такое приложение фактически имеет доступ ко всем продуктам API. Каждое приложение должно быть настроено на доступ как минимум к одному продукту API. Невозможно предоставить доступ ко всем продуктам API неявно. Вы можете настроить приложение на доступ ко всем продуктам API, но это необходимо сделать явно.
 Нет.

Решение: Приложения без API-продуктов

Свяжите учётные данные каждого приложения как минимум с одним продуктом API. Подробнее о том, как это сделать, см. в разделе Регистрация приложений и управление ключами API .

Самый простой способ — назначить каждому приложению доступ ко всем API-продуктам. Это будет эквивалентно возможностям Apigee Edge. Сложность заключается в том, что если вы хотите использовать подход с минимальными привилегиями, вам потребуется определить минимальный список API-продуктов, к которым каждое приложение должно иметь доступ. Вы можете проанализировать это с помощью отчётов Apigee Edge Analytics на основе идентификатора клиента.

Кэш без срока действия

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Кэш(и) не имеют срока годности.

Разница между Apigee Edge и Apigee X:

Апигей Эдж Апигей X
Поддерживает создание, обновление и удаление дескрипторов ресурсов кэша. Не поддерживает создание, обновление или удаление дескрипторов ресурсов кэша.
 Нет

Решение: Кэш без срока действия

Установите срок действия всех кэшей.

Выражения фильтра JSONPath для неопределенных путей

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Для неопределённых путей запрос результата выражений фильтра не входит в спецификацию JSONPath. См. https://goessner.net/articles/JsonPath/ .

Разница между Apigee Edge и Apigee X:

При навигации по этому примеру структуры,

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

С выражением $..books[?(@.name == 'A')][0] ,

Апигей Эдж Апигей X
Выходы '{"name": "A"}' Выходы []

С выражением $..books[?(@.name == 'A')][0].name ,

Апигей Эдж Апигей X
Выходы "A" Выходы []
 Да

Решение: выражения фильтра JSONPath для неопределенных путей

Найдите и замените затронутые запросы.

Выражения JSONPath для отсутствующих индексов

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Выражения JSONPath с отсутствующим индексом ведут себя по-разному в Apigee X и Apigee Edge. Apigee X возвращает ошибку PathNotFoundException если путь не найден.

Разница между Apigee Edge и Apigee X:

При навигации по этому примеру структуры,

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

С выражением $.books[3] ,

Апигей Эдж Апигей X
Выходы null Выводит ошибку PathNotFoundException
 Да

Решение: выражения JSONPath для отсутствующих индексов

Найдите и замените затронутые запросы.

Выражения JSONPath с индексом массива не возвращают объект массива

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Выражения JSONPath с индексом массива или срезами возвращают объект массива в Apigee X.

Разница между Apigee Edge и Apigee X:

При навигации по этому примеру структуры,

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

С выражением $.books ,

Апигей Эдж Апигей X
Выходы {“name”:”A”, “name”: “B”} Выходы [{“name”:”A”, “name”: “B”}]

С выражением $.books[-1] ,

Апигей Эдж Апигей X
Выходы {“name”: “B”} Выходы [{“name”: “B”}]

С выражением $.books[-2:] ,

Апигей Эдж Апигей X
Выходы {“name”:”A”, “name”: “B”} Выходы [{“name”:”A”, “name”: “B”}]
 Да

Решение: выражения JSONPath с индексом массива не возвращают объект массива

Найдите и замените выражения, которые могут вернуть другие результаты после обновления.

Ограничения на имя хранилища ключей

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Имена хранилищ ключей Apigee X могут содержать только буквы, цифры и дефисы. Имена хранилищ ключей Edge не накладывают этих ограничений.

 Нет

Решение: Ограничения на имя хранилища ключей

Проверьте имена хранилищ ключей и при необходимости обновите их, удалив неподдерживаемые символы.

Несколько базовых путей, развернутых для прокси-API

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

В среде развернуто несколько версий прокси-сервера API, и каждая версия имеет свой базовый путь.

Разница между Apigee Edge и Apigee X:

Апигей Эдж Апигей X
Поддерживает развертывание нескольких версий прокси-API, где каждая версия может иметь свой базовый путь. Не поддерживает развертывание нескольких версий прокси-сервера API, даже если прокси-сервер имеет разные базовые пути.
 Нет

Решение: Для API-прокси развернуто несколько базовых путей.

Обновите все пакеты так, чтобы в среде была развернута только одна версия пакета, независимо от базового пути.

Несоответствующие HTTP-сообщения

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Клиенты или API-прокси отправляют сообщения (запросы или ответы), не соответствующие стандарту HTTP. Например, неверные имена заголовков, дублирование некоторых запрещённых заголовков и т. д.

Вы не сможете перейти на Apigee X, если при выполнении вашего API возникает одна или несколько из следующих ошибок:

Ошибка Подробности
НЕДОПУСТИМЫЕ_СИМВОЛЫ_В_ЗАГОЛОВКЕ В указанном заголовке обнаружен один или несколько недопустимых символов. Допустимые имена заголовков состоят из английских букв, цифр и дефисов.
ОТСУТСТВУЮЩАЯ_ДВОЙНАЯ_КИШКА Отсутствует : (двоеточие) в паре имени заголовка и значения заголовка.
MULTIPLE_CONTENT_LENGTH Для заголовка Content-Length предоставлено несколько значений.
CONTENT_LENGTH_NOT_INTEGER Значение заголовка Content-Length не является целым числом.
НЕВЕРНОЕ_ОБНОВЛЕНИЕ Заголовок Upgrade должен использоваться только для включения подключений WebSocket, но это не так.
URL_HEADER_SIZE_TOO_LONG Суммарный размер URL-адреса запроса и заголовков превышает максимально допустимый размер в 15 КБ.
BODY_NOT_ALLOWED Тело сообщения не допускается с методами «GET», «DELETE», «TRACE», «OPTIONS» и «HEAD».
НЕПОДДЕРЖИВАЕМАЯ_ВЕРСИЯ_HTTP Для запроса используется версия HTTP, отличная от 1.1, и она не поддерживается.
ZERO_CONTENT_LENGTH_FOR_POST_OR_PUT Для метода «POST» или «PUT» было установлено нулевое («0») значение поля заголовка Content-Length.
UNSUPPORTED_RESPONSE_PREFIX В заголовке ответа присутствовал неподдерживаемый префикс заголовка «X-Apigee-».
 Да, возможно.

Решение: Несоответствующие HTTP-сообщения

Перед миграцией на Apigee X необходимо исправить все ошибки в протоколах HTTP. Если ошибка возникла в клиентском приложении, необходимо обратиться к разработчику клиентского приложения с просьбой исправить проблему.

Неверное время истечения срока действия токена OAuth 2.0

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Срок действия токена OAuth 2.0 выходит за пределы установленного диапазона.

Разница между Apigee Edge и Apigee X:

Апигей Эдж Апигей X
В настоящее время ограничения на срок действия токена OAuth 2.0 не применяются, но планируется их введение. См. инструкции в разделе «OAuth» на странице «Ограничения» . Для OAuth 2.0 необходимо установить токен доступа и срок действия токена обновления. Поддерживаются следующие диапазоны:
  • 180 секунд <= Срок действия токена доступа OAuth 2.0 <= 30 дней
  • 1 день <= срок действия токена обновления OAuth 2.0 <= 2 года
 Нет

Решение: Неверный срок действия токена OAuth 2.0

Используйте политику OAuthV2 и укажите время истечения срока действия в <ExpiresIn> и <RefreshTokenExpiresIn> .

Превышены лимиты продукта

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Конфигурация Apigee Edge не соответствует установленным ограничениям продукта . Некоторые ограничения продукта, задокументированные, но не применяемые в Apigee Edge, применяются в Apigee X.

 Нет

Решение: превышены лимиты продукта

Перед переходом на Apigee X исправьте любое использование, превышающее ограничения продукта.

Политики ServiceCallout с спецификаторами соединения как конечной точки, так и целевого пути

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

В политике ServiceCallout элемент <LocalTargetConnection> должен включать либо элементы <APIProxy> и <ProxyEndpoint> , либо элемент <Path> , но не оба сразу. Подробнее см. в описании элемента <LocalTargetConnection> .

Apigee Edge документирует это требование, но не обеспечивает его соблюдение. Apigee X прекращает обработку, если обнаруживает <LocalTargetConnection> в обеих конфигурациях.

 Нет

Решение: политики ServiceCallout с указателями как конечной точки, так и целевого пути соединения

Проверьте конфигурации политики ServiceCallout и устраните все конфигурации <LocalTargetConnection> , которые не соответствуют требованиям.

Ограничения имени целевого сервера

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Имена целевых серверов Apigee X могут содержать только буквы, цифры, дефисы и точки. Имена целевых серверов Edge не накладывают этих ограничений.

 Нет

Решение: Ограничения на имя целевого сервера

Проверьте имена целевых серверов и при необходимости обновите их, удалив неподдерживаемые символы.

Пробный сертификат на виртуальном хосте

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Один или несколько виртуальных хостов используют бесплатный пробный сертификат Apigee. Это позволяет виртуальному хосту отвечать на запросы в доменах типа ORG-ENV.apigee.net .

Разница между Apigee Edge и Apigee X:

Апигей Эдж Апигей X
Автоматически настраивает виртуальный хост «по умолчанию» для поддержки доменного имени вида ORG-ENV.apigee.net . Существует подстановочный сертификат, известный как «бесплатный пробный сертификат», который разрешает использование TLS на таких доменах. Устаревшие домены Apigee вида ORG-ENV.apigee.net недоступны в Apigee X. Вам необходимо настроить собственное доменное имя и соответствующим образом предоставить сертификаты.
 Да

Решение: Пробный сертификат на виртуальном хосте

Вам необходимо настроить собственный домен и соответствующим образом предоставить сертификаты.

Любое клиентское приложение, зависящее от устаревшего доменного имени формы ORG-ENV.apigee.net должно быть изменено для вызова нового домена.

Неразрешенный DNS

Краткое содержание Требуются ли изменения на стороне клиента? Разрешение

Целевые конечные точки имеют неразрешенные доменные имена.

Разница между Apigee Edge и Apigee X:

Апигей Эдж Апигей X
Если разрешение DNS не удается, Apigee добавляет .apigee.com к доменному имени, и DNS успешно разрешается с кодом ответа 4xx . Если разрешение DNS не удается, Apigee не выполняет запрос и возвращает код ответа 5xx .
 Нет

Разрешение: Неразрешенный DNS

Обновите целевую конечную точку, указав допустимое доменное имя.