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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметры запроса можно использовать в качестве входных данных для свойства 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, если ваш редактор поддерживает такую возможность. Например, файл может выглядеть следующим образом:

{
    "$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.

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

Вы можете отключить отдельные прокси-серверы, добавив "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.

• AZURE_FUNCTION_PROXY_DISABLE_LOCAL_CALL
• AZURE_FUNCTION_PROXY_BACKEND_URL_DECODE_SLASHES

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

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

Определение объекта 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"
            }
        }
    }
}