В контексте архитектуры или проектирования системы управление API обычно относится к настраиваемому, высокофункциональному обратному прокси-серверу, который используется для управления доступом клиентов (внешних, внутренних или иных) к API, конечной точке или методу. Обычно используемое с RESTful API, но не исключительно, управление API обеспечивает уровень управления запросами и защиты, чтобы входящий запрос можно было проверить, изменить и обработать, а ответ, возвращающийся от серверной системы, можно было дополнительно изменить или обработать. Некоторые организации могут использовать корпоративную сервисную шину (ESB) для достижения аналогичных целей. Корпоративная сервисная шина — это гибко определяемый термин для класса технологий, которые включают дополнительные аспекты, связанные с этим компонентом, но могут извлечь выгоду из того же набора рекомендаций для сервисов управления API.
Примеры систем или технологий управления API включают следующие, а также ряд других:
Шаблоны управления API могут использоваться для предоставления прокси конечным точкам сервисов ArcGIS Enterprise, ArcGIS Online или ArcGIS Location Platform, хотя это может создавать сложности. Клиенты в ArcGIS Online и ArcGIS Enterprise, такие как настраиваемые веб-приложения или ArcGIS Data Pipelines, могут подключаться к сервисам управления API, если они правильно определены, и интегрироваться через это соединение. ArcGIS Pro может подключаться к слоям через управление API, однако этот шаблон может сопровождаться техническими сложностями, и его следует тщательно протестировать.
| Возможности | ArcGIS Online | ArcGIS Enterprise | ArcGIS Location Platform | ArcGIS Pro |
|---|---|---|---|---|
| Управление API |
Полная поддержка Частичная поддержка
Поведение управления API отличается от традиционного обратного прокси-сервера, который обычно перенаправляет весь шаблон HTTP-трафика на внутренний сервер. Например:
<external-host>:443/server/rest/services/* » <internal-host>>:6443/arcgis/rest/services/*
Управление API часто включает в себя выборку отдельных путей URI API и методов HTTP, таких как POST в /routes/extract и PATCH в /routes/<routeid>, что означает, что каждый отдельный метод или шаблон должен быть определен, а также что каждый шаблон может иметь различные правила, поведение и серверные приемники или сервисы. Это часто используется при создании новых API или систем, где существующий набор веб-сервисов не существует, или при реализации архитектуры в стиле микросервисов, где различные серверные компоненты или системы отвечают за обслуживание отдельных запросов API. В некоторых случаях управление API может использовать определение API серверной части, например спецификацию OpenAPI, для создания множества конечных точек или методов интерфейса.
Управление API также обычно включает в себя множество других опций обработки, которые либо манипулируют содержимым запроса, например, чтобы настроить или переписать путь, добавить или изменить заголовок, изменить назначение на основе содержимого тела POST, применяют некоторую фильтрацию к запросу, такую как ограничение скорости, блокировка определенных диапазонов IP-адресов или требование ключей API, либо работают с ответом, чтобы скрыть имена серверов, удалить заголовки ответа или добавить отпечаток пальца или идентификатор. Эти операции определяются на уровне управления API и работают с каждым запросом по мере его отправки и создания ответа.
Все эти шаблоны в целом применимы и к технологиям корпоративных сервисных шин, но с некоторыми отличиями. ESB, как правило, больше ориентированы на синхронную доставку сообщений, где изменение в одной части системы, например, добавляется новая запись или выполняется обновление, вызывает передачу этого изменения в ESB, которая затем преобразует и отправляет сообщение в другие системы, чтобы поддерживать их синхронизацию. В некотором смысле управление API — это скорее методология запросов и опросов, в которой ESB чаще всего вводят строгие обязательства по доставке сообщений, шаблоны издатель-подписчик или другие подобные подходы.
Управление API можно использовать в различных шаблонах с ArcGIS. Как правило, управление API наиболее применимо в случаях, когда оно развертывается перед сервисами на основе ArcGIS Server, такими как картографические, пространственные сервисы или сервисы геообработки, в сценариях, где эти сервисы должны быть доступны либо другой корпоративной системе, либо разработчику, либо конечному клиенту с помощью настроенного приложения.
Вот несколько ключевых соображений по работе с системой управления API:
Управление API обычно лучше всего работает в качестве архитектурного шаблона с автономными развертываниями ArcGIS Server. Обработка обмена токенами и проверки, необходимых для интегрированного сервера в рамках развертывания ArcGIS Enterprise, значительно сложнее и потребует либо расширенной конфигурации ArcGIS, либо конфигурации управления API и знаний для обработки различных запросов аутентификации и конечных точек.
Сервисы ArcGIS REST, к которым обращаются через систему управления API, обычно доступны анонимно, с защитой на уровне сети или межсетевого экрана, а запросы от сервиса управления API отправляются в серверную часть ArcGIS без дальнейших шагов аутентификации. В то время как ArcGIS поддерживает множество шаблонов аутентификации, от встроенных имен пользователей и паролей до SAML и OIDC, шаблон управления API часто предполагает, что внутренний API анонимно доступен для запросов, исходящих из сервиса управления API.
Управление API обычно следует использовать для предоставления доступа к конкретным сервисам или конечным точкам, а не ко всем сайтам ArcGIS Server. Если ваша цель состоит в том, чтобы предоставить доступ ко всему сайту, традиционный обратный прокси является лучшим решением, которое будет более совместимо с более широким набором рабочих процессов.
ArcGIS обычно предоставляет подробные REST API, что означает, что сервис управления API должен поддерживать либо гибкие шаблоны подстановочных знаков, либо только прямые определенные пути. Это особенно актуально, если цель состоит в том, чтобы предоставить сервис клиентскому программному обеспечению ArcGIS, которое спроектировано таким образом, чтобы ожидать полностью доступного API, где можно получить доступ ко всем методам и ресурсам. Например:
/arcgis/rest/services/ServiceName/MapServer/arcgis/rest/services/ServiceName/MapServer/exportImage/arcgis/rest/services/ServiceName/MapServer/0/query/arcgis/rest/services/ServiceName/MapServer/1/queryУправление API становится все более популярным способом обеспечения возможностей интеграции между корпоративными системами. Многие организации инвестируют или создают правила, гарантирующие, что все внутренние транзакции осуществляются через систему управления API, или могут требовать использования управления API для создания сервисов, доступных извне. Рекомендации в контексте системной интеграции включают следующее:
Если цель состоит в том, чтобы применять аутентификацию только на уровне сервиса управления API и чтобы все действия пользователей использовали эту конечную точку, сервисы ArcGIS, определенные как серверные части, обычно должны быть настроены как незащищенные или доступные для всех с публичным или организационным доступом, ограниченным через сетевую конструкцию или брандмауэр, с доступом только через сервис управления API.
Рассмотрите использование URL-адресов веб-контекста и реализацию заголовков, связанных с прокси, чтобы гарантировать, что компонент ArcGIS Server, стоящий за управлением API, знает о проксировании и возвращает действительные URL-адреса, где это возможно.
Ссылки, возвращаемые из запроса через сервис управления API, должны быть проверены и изменены, чтобы использовать правильное имя хоста и контекст для дальнейших запросов. Сервисы управления API часто могут заменять содержимое в теле ответов, например, URL, возвращаемые ArcGIS, что может быть полезно для переопределения ответов на сервере. Например, асинхронный запрос сервиса печати возвращает окончательный URL-адрес результирующего PDF-файла, который затем будет запрошен пользователем, этот URL-адрес может ссылаться на внутреннее имя хоста, а содержимое может быть переписано в системе управления API.
Конечные точки с применёнными шаблонами управления API, такие как геокодирование или маршрутизация, может быть сложнее интегрировать в стандартные интерфейсы ArcGIS. Например, сервис геокодирования, опубликованный через Azure API Management и требующий ключ подписки, может работать не так корректно, как стандартный сервис геокодирования, настроенный для организации ArcGIS Online. См. следующий раздел для получения дополнительной информации.
При работе с сервисами управления API и устранении ошибок клиента сравнивайте запрос, отправленный клиентом через управление API, с запросом, отправленным непосредственно на серверную службу, тщательно изучая HTTP-заголовки и URL для выявления существенных различий.
По определению управление API не включает уровень аутентификации, но многие организации хотят применять аутентификацию к своим конечным точкам управления API в целях проверки пользователей и управления авторизацией. Распространенные методы проверки подлинности на основе управления API включают использование API или ключа подписки, а также интеграцию с методами проверки подлинности на основе OAuth с существующим поставщиком удостоверений (IdP). Каждый из этих шаблонов может создать некоторые проблемы с рабочими процессами интеграции ArcGIS.
Имейте в виду, что методы аутентификации клиентов на основе управления API могут быть несовместимы со стандартными клиентами ArcGIS. Например, если система управления API требует аутентификации на основе заголовков с использованием заголовка, специфичного для сервиса, или заголовка Bearer authorization, стандартные клиенты ArcGIS не смогут динамически добавлять этот заголовок в запросы для поддержки доступа к этому сервису. Аналогичным образом, ключи API могут быть общим уровнем аутентификации, добавляемым через интерфейс управления API, но разработчики приложений должны знать об этом требовании и иметь возможность добавлять его в запросы, чтобы интегрировать эти сервисы в приложение. Различные SDK ArcGIS и шаблоны регистрации сервисов могут поддерживать этот тип ключа подписки или шаблона аутентификации ключа API, но их следует тщательно протестировать, прежде чем предполагать, что шаблон аутентификации подходит.
Аутентификация на основе OAuth для управления API сопряжена и с другими проблемами. При разработке пользовательского приложения с использованием поддерживаемого пакета SDK может быть относительно просто предоставить первоначальное перенаправление в сервис OAuth, вернуть токен или код и использовать этот токен для добавления к дальнейшим запросам в этом сеансе. Однако при использовании готового приложения ArcGIS эту конфигурацию гораздо сложнее успешно использовать, поскольку эти клиенты ожидают прямого доступа к геосервисам ArcGIS без дополнительных шагов аутентификации, которые не управляются ArcGIS.
Как правило, использование API или ключей подписки обеспечивает наиболее успешный путь интеграции в этом контексте со следующими рекомендациями:
Ключи API или подписки должны поддерживать использование в качестве параметров запроса URL. Аутентификация на основе заголовка может поддерживаться для некоторых рабочих процессов, таких как пользовательское приложение на основе Esri Maps SDK или интеграция на основе Python, но для большинства существующих интерфейсов использование заголовка аутентификации, отличного от ArcGIS, в настоящее время невозможно.
Ключи API могут быть добавлены к элементу ресурсов, созданному в последних версиях ArcGIS Online или ArcGIS Enterprise, либо в качестве пользовательского параметра, предоставленного при создании элемента, либо непосредственно к URL, зарегистрированному с элементом. Тщательно протестируйте эти параметры, чтобы оценить, обеспечивают ли они достаточный доступ к запрашиваемому содержимому.
При использовании сервисов, защищенных ключами API в ArcGIS Pro, рабочий процесс Добавить данные из пути также поддерживает использование пользовательских параметров.