Поделиться через

Ограничения и известные проблемы при импорте API

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API

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

  • Поведение Управления API во время импорта OpenAPI.
  • Ограничения на импорт OpenAPI и принцип работы экспорта OpenAPI.
  • Требования и ограничения для импорта WSDL и WADL.

Управление API во время импорта OpenAPI

Во время импорта OpenAPI Управление API делает следующее:

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

Если вы предпочитаете, что необходимые параметры запроса в спецификации претворяются в параметры запроса в Управление API, отключите параметры запроса Include query в параметрах шаблонов операций при создании API на портале. Это также можно сделать с помощью API- создание или обновление REST API для задания свойства queryAPItranslateRequiredQueryParameters.

Для операций GET, HEAD и OPTIONS Управление API отменяет параметр текста запроса, если он определен в спецификации OpenAPI.

Ограничения импорта OpenAPI/Swagger

Если при импорте документа OpenAPI возникают ошибки, убедитесь, что вы проверили его заранее:

  • С помощью конструктора на портале Azure (Конструирование > Внешний интерфейс > Редактор спецификации OpenAPI).
  • Или с помощью стороннего инструмента, например редактора Swagger.

Общие сведения

Требования к шаблонам URL-адресов

Требование Description
Уникальные имена для обязательного пути и параметров запроса В OpenAPI:
  • Имя параметра должно быть уникальным только в пределах расположения (например, пути, запроса, заголовка).
В Управлении API:
  • Можно различать операции по пути и параметрам запроса.
  • OpenAPI не поддерживает такое различение, поэтому мы требуем, чтобы имена параметров были уникальными в пределах всего шаблона URL-адреса. Регистр в именах не учитывается.
Определенный параметр URL-адреса Должен быть частью шаблона URL-адреса.
Доступный URL-файл исходного файла Применяется к относительным URL-адресам сервера.
Указатели \$ref Не должны ссылаться на внешние файлы.

Спецификации OpenAPI

Поддерживаемые версии

Управление API поддерживает только следующее:

  • OpenAPI версии 2.
  • OpenAPI версии 3.0.x (до версии 3.0.3).
  • OpenAPI версии 3.1 (только импорт).

Ограничения размера

Ограничение размера Description
До 4 МБ При импорте спецификации OpenAPI в Управление API.
Размер запроса API Azure Resource Manager Если документ OpenAPI предоставляется по URL-адресу для расположения, доступного из службы "Управление API". См . ограничения подписки Azure.

Поддерживаемые расширения

Поддерживаются следующие расширения:

Расширение Description
x-ms-paths
  • Позволяет определить пути, указанные параметрами запроса в URL-адресе.
  • Рассматриваются в документации по AutoRest.
x-servers Обновление объекта servers OpenAPI 3 для OpenAPI 2.

Неподдерживаемые расширения

Расширение Description
Recursion Управление API не поддерживает определенные рекурсивно определения,
например ссылающиеся на себя схемы.
Объект Server Не поддерживается на уровне операций API.
Ключевое слово Produces Описывает типы MIME, возвращаемые API.
Не поддерживается.

Настраиваемые расширения

  • Игнорируются при импорте.
  • Не сохраняются для экспорта.

Неподдерживаемые определения

Встроенные определения схемы для операций API не поддерживаются. Определения схем:

  • Определены в области API.
  • На них могут быть указаны ссылки в запросе операций API или областях ответов.

Игнорируемые определения

Определения безопасности игнорируются.

Ограничения определений

При импорте параметров запроса поддерживается только метод сериализации массива по умолчанию (style: form, explode: true). Дополнительные сведения о параметрах запроса в спецификациях OpenAPI см. в спецификации сериализации.

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

OpenAPI версия 2

Поддержка OpenAPI версии 2 ограничена только форматом JSON.

Параметры типа Form не поддерживаются. Но вы все равно можете использовать политику для декодирования и проверки полезных данных application/x-www-form-urlencoded и application/form-data.

OpenAPI версии 3.x

Управление API поддерживает следующие версии спецификации:

URL-адреса с HTTPS

  • Если указано несколько параметров servers, Управление API будет использовать первый найденный URL-адрес с HTTPS.
  • Если НЕТ URL-адресов HTTPS, URL-адрес сервера пуст.

Поддерживается

  • example

Не поддерживается

Следующие поля включены в OpenAPI версии 3.0.x или OpenAPI версии 3.1.x, но не поддерживаются:

Object Поле
OpenAPI externalDocs
Info summary
Компоненты
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Операция
  • externalDocs
  • callbacks
  • security
  • servers
Параметр
  • allowEmptyValue
  • style
  • explode
  • allowReserved

Механизмы импорта, обновления и экспорта OpenAPI

Общие сведения

Определения API, экспортированные из службы "Управление API":

  • В основном предназначены для внешних приложений, которым необходимо вызывать API, размещенные в службе "Управление API".
  • Не предназначены для импорта в ту же или другую службу "Управление API".

Чтобы узнать, как управлять конфигурацией определений API в разных службах/средах, ознакомьтесь с документацией по использованию службы "Управление API" с помощью Git.

Добавление нового API с помощью импорта OpenAPI

Для каждой операции, найденной в документе OpenAPI, создается новая операция с помощью:

  • Для имени ресурса Azure задано значение operationId.

    • Значение operationId нормализовано.
    • Если operationId значение имени ресурса Azure не указано (отсутствует nullили пусто), создается путем объединения метода HTTP и шаблона пути.
      • Например, get-foo.

  • Для отображаемого имени задано значение summary.

    • summary Значение:
      • Импортируется как есть.
      • Максимальная длина — 300 символов.
    • Если свойство summary не указано (т. е. отсутствует, имеет значение null или пустое), для отображаемого имени будет задано значение operationId.

Правила нормализации для operationId

  • Преобразовать в нижний регистр.
  • Замените каждую последовательность символов, отличных от буквенно-цифровых, одним тире.
    • Например, GET-/foo/{bar}?buzz={quix} преобразуется в get-foo-bar-buzz-quix-.
  • Удалите тире с обеих сторон.
    • Например, get-foo-bar-buzz-quix- становится get-foo-bar-buzz-quix
  • Выполните усечение, чтобы длина не превышала 76 символов, что на четыре символа меньше максимального ограничения для имени ресурса.
  • При необходимости используйте оставшиеся четыре символа для суффикса дедупликации в формате -1, -2, ..., -999.

Обновление имеющегося API с помощью импорта OpenAPI

Во время импорта существующая операция API:

  • Изменяется в соответствии с API, описанным в документе OpenAPI.
  • Обеспечивает соответствие операции в документе OpenAPI, сравнивая ее значение operationId с именем ресурса Azure существующей операции.
    • Если совпадение найдено, свойства существующей операции обновляются на месте.
    • Если совпадение не найдено:
      • Новая операция создается путем объединения метода HTTP и шаблона пути, например get-foo.
      • Для каждой новой операции процесс импорта попытается скопировать политики из имеющейся операции с использованием одного и того же метода HTTP и шаблона пути.

Удаляются все существующие несоответствуемые операции.

Чтобы сделать импорт более предсказуемым, следуйте таким рекомендациям:

  • Указывайте свойство operationId для каждой операции.
  • Необходимо избегать изменения operationId после первоначального импорта.
  • Никогда не изменяйте operationId и метод HTTP или шаблон пути одновременно.

Правила нормализации для operationId

  • Преобразовать в нижний регистр.
  • Замените каждую последовательность символов, отличных от буквенно-цифровых, одним тире.
    • Например, GET-/foo/{bar}?buzz={quix} преобразуется в get-foo-bar-buzz-quix-.
  • Удалите тире с обеих сторон.
    • Например, get-foo-bar-buzz-quix- становится get-foo-bar-buzz-quix
  • Выполните усечение, чтобы длина не превышала 76 символов, что на четыре символа меньше максимального ограничения для имени ресурса.
  • При необходимости используйте оставшиеся четыре символа для суффикса дедупликации в формате -1, -2, ..., -999.

Экспорт API в качестве OpenAPI

Для каждой операции это:

  • Имя ресурса Azure экспортируется в виде operationId.
  • Отображаемое имя экспортируется в виде summary.

Обратите внимание, что нормализация operationId выполняется при импорте, а не при экспорте.

WSDL

Вы можете создать сквозную передачу SOAP и API для преобразования между SOAP и REST с помощью WSDL-файлов.

Привязки SOAP

  • Поддерживаются только привязки SOAP со стилем кодирования document и literal.
  • Шифрование SOAP типа rpc не поддерживается.

Директивы imports и include

  • Директивы wsdl:import, xsd:import и xsd:include не поддерживаются. Вместо этого объедините зависимости в один документ.

  • Средство с открытым кодом для разрешения и объединения зависимостей wsdl:import, xsd:import и xsd:include в WSDL-файле см. в этом репозитории GitHub.

Спецификации WS-*

Файлы WSDL, включающие спецификации WS-*, не поддерживаются.

Сообщения из нескольких частей

Сообщения такого типа не поддерживаются.

wsHttpBinding для WCF

  • Службы SOAP, созданные с помощью Windows Communication Foundation, должны использовать basicHttpBinding.
  • wsHttpBinding не поддерживается.

MTOM

  • Службы, использующие MTOMмогут работать.
  • Официальная поддержка сейчас не предоставляется.

Рекурсия

  • Типы, определенные рекурсивно, не поддерживаются Управление API.
  • Например, это касается типов, которые ссылаются на включающих их массив.

Несколько пространств имен

Хотя в схеме можно использовать несколько пространств имен, для определения частей сообщений можно использовать только целевое пространство имен. Эти пространства имен используются для определения других входных или выходных элементов.

Пространства имен, отличные от целевого объекта, не сохраняются при экспорте. Хотя вы можете импортировать документ WSDL, определяющий части сообщений, с другими пространствами имен, все части сообщений будут иметь целевое пространство имен WSDL при экспорте.

Несколько конечных точек

Файлы WSDL могут определять несколько служб и конечных точек (портов) одним или несколькими wsdl:servicewsdl:port элементами. Однако шлюз Управление API может импортировать и прокси-запросы только к одной службе и конечной точке. Если в WSDL-файле определены несколько служб или конечных точек, определите имя целевой службы и конечную точку при импорте API с помощью свойства wsdlSelector .

Совет

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

Массивы

Преобразование между SOAP и REST поддерживает только заключенные в оболочку массивы, показанные в следующем примере:

    <complexType name="arrayTypeName">
        <sequence>
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="typeName">
        <sequence>
            <element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
            <element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
            <element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
        </sequence>
    </complexType>

WADL

У нас нет сведений о проблемах импорта с помощью формата WADL.