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

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

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

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

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

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

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

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

Если вы предпочитаете, чтобы обязательные параметры запроса в спецификации преобразовывались в параметры запроса в Управлении API, отключите настройку Include query parameters in operation templates при создании API на портале. Этот параметр также можно сделать с помощью API — создание или обновление REST API, чтобы задать для свойства API translateRequiredQueryParameters значение query.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Расширение Описание
x-ms-paths
x-servers Обратное портирование объекта OpenAPI 3servers для OpenAPI 2.

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

Расширение Описание
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, но не поддерживаются:

Объект Поле
OpenAPI externalDocs
Информация summary
Компоненты
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem (ЭлементPathItem)
  • trace
  • servers
Операция
  • externalDocs
  • callbacks
  • security
  • servers
  • deprecated
Параметр
  • allowEmptyValue
  • style
  • explode
  • allowReserved
  • deprecated
Шаблон сервера
  • API Server and Base URL

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

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

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

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

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

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

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

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

    • Значение operationId нормализовано.
    • Если operationId не указан (отсутствует, null или пуст), имя ресурса Azure создается путем объединения метода 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».
  • Нет поддержки стиля RPC или кодировки SOAP.

Директивы 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, могут работать.
  • Официальная поддержка сейчас не предоставляется.

Рекурсия

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

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

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

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

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

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

Совет

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

Массивы

Преобразование SOAP-to-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.

  • Last updated on