Работа с устаревшими прокси-серверами

Статья
06/01/2023

Внимание

Функции Azure прокси-серверы — это устаревшая функция для версий 1.x до 3.x среды выполнения Функции Azure. Поддержка прокси-серверов может быть повторно включена в версии 4.x для успешного обновления приложений-функций до последней версии среды выполнения. Как можно скорее необходимо перейти на интеграцию приложений-функций с Azure Управление API. Управление API позволяет воспользоваться преимуществами более полного набора функций для определения, защиты, администрации и монетизации API на основе Функций. Дополнительные сведения см. в разделе Управление API интеграции.

Сведения о том, как повторно включить поддержку прокси-серверов в Функциях версии 4.x, см. в статье "Повторное включение прокси-серверов" в Функциях версии 4.x.

Чтобы упростить миграцию из существующих реализаций прокси-сервера, в этой статье приведены ссылки на эквивалентное содержимое Управления API (при наличии).

В этой статье описано, как настроить прокси Функций Azure и работать с ними. Эта функция позволяет указать конечные точки в приложении-функции, реализуемые другим ресурсом. Эти прокси можно использовать для разбиения большого API-интерфейса на несколько приложений-функций (как в архитектуре микрослужб), сохраняя при этом единую область API для клиентов.

На выполнение прокси-сервера распространяется стандартная тарификация службы "Функции". Дополнительные сведения см. на странице цен на Функции Azure.

Повторное включение прокси-серверов в Функциях версии 4.x

После переноса приложения-функции в среду выполнения функций версии 4.x необходимо специально повторно добавлять прокси-серверы. Вы по-прежнему должны переключиться на интеграцию приложений-функций с Azure Управление API как можно скорее, а не только на основе прокси-серверов.

Повторное включение прокси-серверов требует установки флага в параметре AzureWebJobsFeatureFlags приложения одним из следующих способов:

AzureWebJobsFeatureFlags Если параметр еще не существует, добавьте этот параметр в приложение-функцию со значениемEnableProxies.
Если этот параметр уже существует, добавьте ,EnableProxies в конец существующего значения.

AzureWebJobsFeatureFlags — это массив флагов с разделителями-запятыми, используемый для включения предварительной версии и других временных функций. Дополнительные сведения о создании и изменении параметров приложения см. в статье "Работа с параметрами приложения".

Примечание.

Даже при повторном использовании флага EnableProxies вы не можете работать с прокси-серверами в портал Azure. Вместо этого необходимо работать непосредственно с файлом proxies.json для приложения-функции. Дополнительные сведения см. в разделе Расширенная конфигурация.

Создание прокси-сервера

Внимание

Эквивалентное содержимое про Управление API см. в статье Предоставление бессерверных API-интерфейсов из конечных точек HTTP с помощью Управления API Azure.

Прокси-серверы определяются в файле proxies.json в корне приложения-функции. В этом разделе показано, как использовать портал Azure для создания этого файла в приложении-функции. Редактирование на портале поддерживается не для всех языков и сочетаний операционных систем. Если вы не можете изменить файлы приложения-функции на портале, вы можете создать и развернуть эквивалентный файл proxies.json из корневой папки локального проекта. Дополнительные сведения о поддержке редактирования портала см. в разделе Сведения о языковой поддержке.

Откройте портал Azure и перейдите к своему приложению-функции.
В меню слева выберите Прокси-серверы, а затем нажмите +Добавить.
Задайте имя прокси.
Настройте конечную точку в этом приложении-функции, указав шаблон маршрута и методы HTTP. Поведение этих параметров соответствует правилам для триггеров HTTP.
Задайте URL-адрес внутреннего сервера для другой конечной точки. Ею может быть функция в другом приложении-функции или другой API. Значение не обязательно должно быть статическим и может ссылаться на параметры приложения и параметры исходного запроса клиента.
Нажмите кнопку создания.

Прокси теперь существует в виде новой конечной точки в приложении-функции. С точки зрения клиента это то же самое, что и HttpTrigger в Функциях. Вы можете попробовать новый прокси-сервер, скопировав URL-адрес прокси-сервера и протестировав его с помощью клиента HTTP.

Изменение запросов и ответов

Внимание

В службе Управления API вы можете могут изменять поведение API посредством настройки с помощью политик. Политика — это коллекция правил, которые выполняются последовательно над запросом или ответом API. Дополнительные сведения о политиках Управления API см. в статье Политики в Azure API Management.

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

Изменение запроса внутреннего сервера

По умолчанию запрос внутреннего сервера инициализируется в качестве копии исходного запроса. Кроме настройки URL-адреса внутреннего сервера вы также можете изменить метод, заголовки и параметры строки запроса HTTP. Измененные значения могут ссылаться на параметры приложения и параметры исходного запроса клиента.

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

Изменение ответа

По умолчанию ответ клиента инициализируется в качестве копии ответа внутреннего сервера. Вы можете изменить код состояния, описание, заголовки и текст ответа. Измененные значения могут ссылаться на параметры приложения, параметры исходного запроса клиента и параметры ответа внутреннего сервера.

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

Использование переменных

Использовать статическую конфигурацию для прокси-сервера необязательно. Вы можете настроить для него использование переменных из исходного клиентского запроса, ответа внутреннего сервера или параметров приложения.

Ссылки на локальные функции

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

"backendUri": "https://localhost/api/httptriggerC#1" будет ссылаться на локальную функцию, активируемую HTTP, на маршруте /api/httptriggerC#1.

Примечание.

Если функция использует уровень авторизации функции, администратора или системы, вам нужно указать код и идентификатор клиента в соответствии с исходным URL-адресом функции. В этом случае ссылка будет выглядеть следующим образом: "backendUri": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>". Мы рекомендуем хранить эти ключи в Параметры приложения и использовать их в прокси-серверах. Это позволяет избежать хранения секретных значений в исходном коде.

Ссылки на параметры запроса

Параметры запроса можно использовать в качестве входных данных для свойства URL-адреса внутреннего сервера или в рамках изменения запросов и ответов. Некоторые параметры могут быть связаны с шаблоном маршрута, указанным в основной конфигурации прокси-сервера, тогда как другие задаются в соответствии со свойствами входящих запросов.

Параметры шаблона маршрута

Параметры, используемые в шаблоне маршрута, указываются по именам, которые заключаются в фигурные скобки — {}.

Например, если прокси-сервер использует шаблон маршрута, подобный /pets/{petId}, URL-адрес внутреннего сервера может содержать значение {petId}, как в https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. Если шаблон маршрута заканчивается подстановочным знаком, например /api/{*restOfPath}, значение {restOfPath} будет строковым представлением остальных сегментов пути входящего запроса.

Дополнительные параметры запроса

В дополнение к параметрам шаблона маршрута вы можете использовать следующие значения конфигурации:

{request.method}. Метод HTTP, используемый в исходном запросе.
{request.headers.<имя_заголовка>}. Заголовок, который можно считать из исходного запроса. Замените <имя_заголовка> именем заголовка, который вы собираетесь считать. Если заголовок не включен в запрос, в качестве значения будет отображаться пустая строка.
{request.querystring.<имя_параметра>}. Параметр строки запроса, который можно считать из исходного запроса. Замените <имя_параметра> именем параметра, который вы собираетесь считать. Если параметр не включен в запрос, в качестве значения будет отображаться пустая строка.

Ссылки на параметры ответа внутреннего сервера

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

{backend.response.statusCode}. Код состояния HTTP, возвращаемый для ответа внутреннего сервера.
{backend.response.statusReason}. Код состояния HTTP, возвращаемый для ответа внутреннего сервера.
{backend.response.headers.<имя_заголовка>}. Заголовок, который можно считать из ответа внутреннего сервера. Замените <имя_заголовка> именем заголовка, который вы собираетесь считать. Если заголовок не включен в ответ, в качестве значения будет отображаться пустая строка.

Ссылки на параметры приложения

Вы также можете ссылаться на параметры приложения, определенные для приложения-функции, поставив знаки процента (%) перед именем параметра и после него.

Например, в URL-адресе внутреннего сервера https://%ORDER_PROCESSING_HOST%/api/orders %ORDER_PROCESSING_HOST% будет заменено значением параметра ORDER_PROCESSING_HOST.

Совет

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

Устранение неполадок функции "Прокси-серверы"

Добавьте флаг "debug":true к любому прокси-серверу в proxies.json, чтобы включить ведение журнала отладки. Журналы хранятся в папке D:\home\LogFiles\Application\Proxies\DetailedTrace. К ним можно получить доступ с помощью дополнительных инструментов (Kudu). Каждый HTTP-ответ также будет содержать заголовок Proxy-Trace-Location с URL-адресом для доступа к файлу журнала.

Чтобы отладить прокси-сервер на стороне клиента, добавьте заголовок Proxy-Trace-Enabled с заданным значением true. При этом также будут записываться журналы трассировки в файловую систему и URL-адрес трассировки будет возвращаться в качестве заголовка в ответе.

Блокирование трассировок прокси-сервера

В целях безопасности вы можете запретить всем пользователям вызывать службу для создания файлов трассировки. Пользователи не смогут получить доступ к содержимому трассировки без ваших учетных данных для входа. Но создание файлов трассировки связано с потреблением ресурсов и свидетельствует о том, что вы используете прокси-серверы Функций Azure.

Чтобы полностью отключить трассировку, добавьте "debug":false для конкретного прокси-сервера в proxies.json.

Расширенная конфигурация

Настроенные прокси-серверы хранятся в файле proxies.json, расположенном в корневом каталоге приложения-функции. Вы можете вручную изменить этот файл и развернуть его как часть приложения, используя любой из методов развертывания, поддерживаемых Функциями.

Совет

Если вы не настроили ни один из методов развертывания, вы можете сделать это в файле proxies.json. Перейдите к приложению-функции и выберите Функции платформы, а затем — Редактор службы приложений. Так вы сможете просмотреть всю структуру файла приложения-функции и внести изменения.

Файл proxies.json определяется объектом proxies, который состоит из именованных прокси-серверов и их определений. При необходимости для автозавершения кода можно ссылаться на схему JSON, если ваш редактор поддерживает такую возможность. Например, файл может выглядеть следующим образом:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

Каждый прокси имеет понятное имя, как например proxy1 в предыдущем примере. Соответствующий объект определения прокси определяется следующими свойствами:

matchCondition (обязательное) — объект, который определяет запросы, активирующие выполнение этого прокси-сервера. Он содержит два свойства, которые совместно используются триггерами HTTP:
- methods — массив методов HTTP, на которые отвечает прокси-сервер. Если свойство не указано, прокси-сервер будет отвечать на все методы HTTP в маршруте.
- route (обязательное) — шаблон маршрута, определяющий URL-адреса запросов, на которые будет отвечать прокси-сервер. В отличие от триггеров HTTP значение по умолчанию отсутствует.
backendUri — URL-адрес внутреннего ресурса, к которому должен быть отправлен запрос. Это значение может ссылаться на параметры приложения и параметры исходного запроса клиента. Если это свойство не включено, решение "Функции Azure" вернет ответ HTTP 200 OK.
requestOverrides. Объект, определяющий преобразование запросов внутреннего сервера. Ознакомьтесь с разделом Определение объекта requestOverrides.
responseOverrides. Объект, определяющий преобразование ответа клиента. Ознакомьтесь с разделом Определение объекта responseOverrides.

Примечание.

Свойство route в функции "Прокси-серверы Функций Azure" не учитывает свойство routePrefix конфигурации узла приложения-функции. Если вы хотите включить префикс, например /api, он должен быть включен в свойство route.

Отключение отдельных прокси-серверов

Вы можете отключить отдельные прокси-серверы, добавив "disabled": true для прокси-сервера в файле proxies.json. В результате для всех запросов, соответствующих значению matchCondition, будет возвращаться ошибка 404.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "Root": {
            "disabled":true,
            "matchCondition": {
                "route": "/example"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

Параметры приложения

Поведением прокси-сервера можно управлять с помощью нескольких параметров приложения. Сведения о них можно узнать из статьи Справочник по параметрам приложений для Функций Azure.

Зарезервированные символы (форматирование строк)

Прокси-серверы считывают все строки из JSON-файла, используя \ как escape-символ. Кроме того, прокси-серверы интерпретируют фигурные скобки. См. полный список примеров ниже.

Символ	Экранируемый символ	Пример
{ или }	{{ или }}	`{{ example }}` -->`{ example }`
\	\\	`example.com\\text.html` -->`example.com\text.html`
"	\"	`\"example\"` -->`"example"`

Определение объекта requestOverrides

Объект requestOverrides определяет изменения, внесенные в запрос во время вызова внутреннего ресурса. Объект определяется следующими свойствами:

backend.request.method — метод HTTP, используемый для вызова внутреннего сервера.
backend.request.querystring.<имя_параметра> — параметр строки запроса, который можно задать для вызова внутреннего сервера. Замените <имя_параметра> именем параметра, который вы собираетесь задать. Если указана пустая строка, параметр все равно включается в запрос внутреннего сервера.
backend.request.headers.<имя_заголовка> — заголовок, который можно задать для вызова внутреннего сервера. Замените <имя_заголовка> именем заголовка, который вы собираетесь задать. Если указана пустая строка, параметр все равно включается в запрос внутреннего сервера.

Значения могут ссылаться на параметры приложения и параметры исходного запроса клиента.

Пример конфигурации может выглядеть следующим образом:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>",
            "requestOverrides": {
                "backend.request.headers.Accept": "application/xml",
                "backend.request.headers.x-functions-key": "%ANOTHERAPP_API_KEY%"
            }
        }
    }
}

Определение объекта responseOverrides

Объект requestOverrides определяет изменения, внесенные в ответ, который передается обратно к клиенту. Объект определяется следующими свойствами:

response.statusCode. Код состояния HTTP, который будет возвращен клиенту.
response.statusReason. Описание HTTP, которое будет возвращено клиенту.
response.body. Строковое представление текста, который будет возвращен клиенту.
response.headers.<имя_заголовка>. Заголовок, который можно задать для ответа клиенту. Замените <имя_заголовка> именем заголовка, который вы собираетесь задать. Если указана пустая строка, заголовок не включается в ответ.

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

Пример конфигурации может выглядеть следующим образом:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "responseOverrides": {
                "response.body": "Hello, {test}",
                "response.headers.Content-Type": "text/plain"
            }
        }
    }
}

Примечание.

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

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

Работа с устаревшими прокси-серверами

Повторное включение прокси-серверов в Функциях версии 4.x

Создание прокси-сервера

Изменение запросов и ответов

Изменение запроса внутреннего сервера

Изменение ответа

Использование переменных

Ссылки на локальные функции

Ссылки на параметры запроса

Параметры шаблона маршрута

Дополнительные параметры запроса

Ссылки на параметры ответа внутреннего сервера

Ссылки на параметры приложения

Устранение неполадок функции "Прокси-серверы"

Блокирование трассировок прокси-сервера

Расширенная конфигурация

Отключение отдельных прокси-серверов

Параметры приложения

Зарезервированные символы (форматирование строк)

Определение объекта requestOverrides

Определение объекта responseOverrides

Обратная связь

Дополнительные ресурсы