Azure API Gateway

Um sistema Azure que fornece APIs a aplicações externas deve usar uma Gateway para essas APIs, a Azure API Gateway. A API Gateway permite organizar e publicar as APIs do sistema, públicas ou protegidas, disponibilizando-as a programadores, parceiros, clientes e mesmo clientes internos se for caso disso. A API Gateway tem a infra-estrutura e monitorização necessárias à disponibilização de uma API mediante pagamento.

A Gateway deve ser pensada como proxy ou nível de indirecção entre os clientes e as operações de todas as APIs.

A Gateway tem um portal que pode ser usado para publicar, gerir e monitorizar as APIs do sistema, e um outro portal para os clientes se autenticarem, criarem as suas chaves de acesso, reportar incidentes ou problemas e ler a documentação das APIs.

Pré-requisitos

Pressupõe-se a criação de Azure Function do tipo HTTP Trigger com o nível de autorização configurado com o valor Function.
No exemplo, GetName.

public static class GetName
    {
        [FunctionName("GetName")]
        public static async Task<HttpResponseMessage> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)]HttpRequestMessage req, TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            // parse query parameter
            string name = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
                .Value;

            // Get request body
            dynamic data = await req.Content.ReadAsAsync<object>();

            // Set name to query string or body data
            name = name ?? data?.name;

            return name == null
                ? req.CreateResponse(HttpStatusCode.BadRequest, "Please pass a name on the query string or in the request body")
                : req.CreateResponse(HttpStatusCode.OK, "Hello " + name + ", you are great!");
        }
    }

Pressupõe-se a criação de uma instância de API Management do Azure. Para exemplo, testingapisclopes.

Criação da definição OpenAPI (Swagger)

Depois de testar a função, seleccionar a opção Integrate da nova função e indicar os verbos HTTP permitidos.
Na Function App desta nova função, seleccionar Platform Features e API Definition. É apresentada a página para definição da API (Swagger) idêntica à seguinte. Na API Definition, seleccionar o valor Function.

Seleccionar Generate API definition template > Save.

O Azure varre a Function App à procura das funções do tipo HTTP Trigger e usa a informação do functions.json para gerar a definição OpenAPI.
Uma vez gerada a template da definição, completa-se com os metadados das operações e das estruturas de dados e grava-se.

Testar a OpenAPI

Na opção Manage da nova função, copiar a chave definida por omissão (default key) para as chaves do host (Host Keys).
Voltar à página de Definição da API (Function App Name > Platform features > API definition) e no painel da direita seleccionar change authentication, colar a chave definida por omissão e seleccionar authenticate.
Testar a operação através da acção Try this operation e verificar o output.

Importação da API para o API Management

Como a Function App está protegida por uma chave, há que criar uma entrada do tipo Named Value e aplicar a política set-query-parameter policy para que a chave seja adicionada automaticamente quando a Function App é invocada a partir do APIM. A Gestão de APIs distingue as APIs pelo respectivo sufixo. Por exemplo, functionappapi.

Testar a nova API APIM no portal do Azure

Seleccionar a API recém criada, escolher o separador Test e seleccionar o método a testar. GetName, por exemplo. A página apresenta os campos para os parâmetros de consulta, como por exemplo name. A página também apresenta os campos para os cabeçalhos. Um dos campos de cabeçalho é "Ocp-Apim-Subscription-Key", para a chave de subscrição do produto que está associado esta API. Quem cria a instância APIM é administrador por omissão, pelo que a chave é automaticamente preenchida.
Uma vez conferidos os campos, seleccionar Send.
O Back-end responde com 200 OK e o corpo da resposta.

Testar a nova API APIM no portal do Programador

Seleccionar a API a testar e o método a testar. A página também apresenta os campos para os cabeçalhos. Um dos campos de cabeçalho é "Ocp-Apim-Subscription-Key", para a chave de subscrição do produto que está associado esta API. Quem cria a instância APIM é administrador por omissão, pelo que a chave é automaticamente preenchida.
Depois de conferidos os campos, seleccionar Try It.
Uma vez invocada a operação, o portal do programador apresenta o status da resposta, os cabeçalhos da resposta e o corpo ou conteúdo da resposta.

Exemplo de pedido HTTP

GET https://testingapisclopes.azure-api.net/functionappapi/api/GetName?name=48 HTTP/1.1
Host: testingapisclopes.azure-api.net
Ocp-Apim-Subscription-Key: fc1767dcf0b448ce9c9d6d3cfcea5739

Referências: Import an API from a Function App now available in the APIs blade, Create an OpenAPI definition for a function, Importar e publicar a sua primeira API

Licença CC BY-SA 4.0 Silvia Pinhão Lopes, 17.12.17