Integrar Gestão de API com o Service Fabric no Azure

A implementação da Gestão de API do Azure no Service Fabric é um cenário avançado. A Gestão de API é útil se tiver de publicar APIs com um conjunto avançado de regras de encaminhamento para os seus serviços de back-end do Service Fabric. Geralmente, as aplicações da cloud precisam de um gateway de front-end que forneça um único ponto de entrada para utilizadores, dispositivos ou outras aplicações. No Service Fabric, esse gateway pode ser qualquer serviço, sem estado, concebido para a entrada de tráfego, tal como uma aplicação ASP.NET Core, os Hubs de Eventos, o Hub IoT ou a Gestão de API do Azure.

Este artigo mostra-lhe como configurar o Azure Gestão de API com o Service Fabric para encaminhar o tráfego para um serviço de back-end no Service Fabric. Quando tiver terminado, terá implementado a Gestão de API numa VNET e configurado uma operação de API para enviar tráfego para serviços sem estado de back-end. Para saber mais sobre os cenários da Gestão de API do Azure com o Service Fabric, veja o artigo Overview (Descrição Geral).

Nota

Recomendamos que utilize o módulo Azure Az PowerShell para interagir com o Azure. Veja Instalar o Azure PowerShell para começar. Para saber como migrar para o módulo do Az PowerShell, veja Migrar o Azure PowerShell do AzureRM para o Az.

Disponibilidade

Importante

Esta funcionalidade está disponível nos escalões Premium e Programador do Gestão de API devido ao suporte de rede virtual necessário.

Pré-requisitos

Antes de começar:

• Se não tiver uma subscrição do Azure, crie uma conta gratuita
• Instale Azure PowerShell ou a CLI do Azure.
• Crie um cluster do Windows seguro num grupo de segurança de rede.
• Se implementar um cluster do Windows, configure um ambiente de desenvolvimento do Windows. Instale o Visual Studio 2019 e as cargas de trabalho de desenvolvimento para várias plataformas do Azure, desenvolvimento ASP.NET e Web e .NET Core . Em seguida, configure um ambiente de desenvolvimento .NET.

Topologia da rede

Agora que tem um cluster do Windows seguro no Azure, implemente Gestão de API na rede virtual (VNET) na sub-rede e no NSG designados para Gestão de API. Para este artigo, o modelo de Gestão de API Resource Manager está pré-configurado para utilizar os nomes da VNET, da sub-rede e do NSG que configurou no tutorial do cluster do Windows Este artigo implementa a seguinte topologia no Azure na qual Gestão de API e o Service Fabric estão em sub-redes do mesmo Rede Virtual :

Iniciar sessão no Azure e selecionar a sua subscrição

Inicie sessão na sua conta do Azure, selecione a sua subscrição antes de executar os comandos do Azure.

Connect-AzAccount
Get-AzSubscription
Set-AzContext -SubscriptionId <guid>

az login
az account set --subscription <guid>

Implementar um serviço de back-end do Service Fabric

Antes de configurar a Gestão de API para encaminhar o tráfego para um serviço de back-end do Service Fabric, primeiro precisa de um serviço em execução para aceitar pedidos.

Crie um ASP.NET Core Reliable Service sem estado básico com o modelo de projeto de API Web predefinido. Como resultado, é criado um ponto final de HTTP para o seu serviço, que vai expor através da Gestão de API do Azure.

Inicie o Visual Studio como Administrador e crie um serviço ASP.NET Core:

1. No Visual Studio, selecione Ficheiro –> Novo Projeto.

2. Selecione o modelo de Aplicação do Service Fabric em Cloud e dê-lhe o nome "ApiApplication".

3. Selecione o modelo de serviço sem estado ASP.NET Core e dê ao projeto o nome "WebApiService".

4. Selecione o modelo de projeto API Web ASP.NET Core 2.1.

5. Uma vez criado o projeto, abra PackageRoot\ServiceManifest.xml e remova o atributo Port da configuração do recurso do ponto final:

   <Resources>
     <Endpoints>
       <Endpoint Protocol="http" Name="ServiceEndpoint" Type="Input" />
     </Endpoints>
   </Resources>
   

   A remoção da porta permite que o Service Fabric especifique dinamicamente uma porta a partir do intervalo de portas da aplicação, aberta através do Grupo de Segurança de Rede no modelo cluster Resource Manager, permitindo que o tráfego flua para a mesma a partir de Gestão de API.

6. Prima F5 no Visual Studio para verificar se a API Web está disponível localmente.

   Abra o Service Fabric Explorer e desagregue para uma instância específica do serviço ASP.NET Core para ver o endereço base no qual o serviço está a escutar. Adicione /api/values ao endereço base e abra num browser, o que invoca o método Get em ValuesController no modelo da API Web. Esta ação devolve a resposta predefinida que o modelo fornece, uma matriz JSON que contém duas cadeias:

   ["value1", "value2"]`
   

   Este é o ponto final que vai expor através da Gestão de API no Azure.

7. Por fim, implemente a aplicação no seu cluster no Azure. No Visual Studio, clique com o botão direito do rato no projeto Aplicação e selecione Publicar. Indique o ponto final do cluster (por exemplo, mycluster.southcentralus.cloudapp.azure.com:19000) para implementar a aplicação no cluster do Service Fabric no Azure.

Deve estar agora a ser executado no cluster do Service Fabric no Azure um serviço sem estado ASP.NET Core com o nome fabric:/ApiApplication/WebApiService.

Transferir e compreender os modelos do Azure Resource Manager

Transfira e guarde os modelos do Resource Manager e o ficheiro de parâmetros seguintes:

• network-apim.json
• network-apim.parameters.json
• apim.json
• apim.parameters.json

O modelo network-apim.json implementa uma sub-rede e um grupo de segurança de rede novos na rede virtual em que está implementado o cluster do Service Fabric.

As secções seguintes descrevem os recursos que o modelo apim.json define. Para obter mais informações, siga as ligações para a documentação de referência do modelo em cada secção. Os parâmetros configuráveis definidos no ficheiro de parâmetros apim.parameters.json vão ser definidos mais adiante neste artigo.

Microsoft.ApiManagement/service

Microsoft.ApiManagement/service descreve a instância do serviço Gestão de API: nome, SKU ou camada, localização do grupo de recursos, informações do publicador e rede virtual.

Microsoft.ApiManagement/service/certificates

Microsoft.ApiManagement/service/certificates configura a segurança da Gestão de API. A Gestão de API tem de se autenticar com o seu cluster do Service Fabric para a deteção de serviço através de um certificado de cliente que tenha acesso ao cluster. Este artigo utiliza o mesmo certificado especificado anteriormente ao criar o cluster do Windows, que por predefinição pode ser utilizado para aceder ao cluster.

Este artigo utiliza o mesmo certificado para autenticação de cliente e segurança de nó para nó de cluster. Se tiver configurado um certificado de cliente separado, pode utilizá-lo para aceder ao seu cluster do Service Fabric. Indique o nome, a palavra-passe e os dados (cadeia com codificação base 64) do ficheiro de chave privada (.pfx) do certificado de cluster que especificou quando criou o cluster do Service Fabric.

Microsoft.ApiManagement/service/backends

Microsoft.ApiManagement/service/backends descreve o serviço de back-end para o qual o tráfego é reencaminhado.

Nos back-ends do Service Fabric, o cluster do Service Fabric é o back-end em vez de um serviço específico do Service Fabric. Isto permite que uma única política encaminhe para mais de um serviço no cluster. O campo url aqui é o nome completamente qualificado de um serviço no seu cluster para o qual todos os pedidos são encaminhados por predefinição caso não seja especificado qualquer nome de serviço numa política de back-end. Pode utilizar um nome de serviço fictício, tal como "fabric:/ficticio/servico" se não pretender ter um serviço de contingência. resourceId especifica o ponto final da gestão do cluster. clientCertificateThumbprint e serverCertificateThumbprints identificam os certificados utilizados para autenticar no cluster.

Microsoft.ApiManagement/service/products

Microsoft.ApiManagement/service/products cria um produto. Na Gestão de API do Azure, os produtos contêm uma ou mais APIs, bem como quotas de utilização e os termos de utilização. Depois de um produto ser publicado, os programadores podem subscrevê-lo e começar a utilizar as APIs do mesmo.

Introduza um displayName (nome a apresentar) e uma description (descrição) relevantes para o produto. Para este artigo, é necessária uma subscrição, mas a aprovação da subscrição por um administrador não é. O estado deste produto é "publicado" e está visível para os subscritores.

Microsoft.ApiManagement/service/apis

Microsoft.ApiManagement/service/apis cria uma API. Uma API na Gestão de API representa um conjunto de operações que podem ser invocadas por aplicações cliente. Depois de as operações serem adicionadas, a API é adicionada a um produto e pode ser publicada. Após a publicação da API, esta pode ser subscrita e os programadores podem utilizá-la.

• displayName pode ser qualquer nome para a API. Para este artigo, utilize "Aplicação do Service Fabric".
• name indica um nome exclusivo e descritivo para a API, como "service-fabric-app". É apresentado no portais do programador e do editor.
• serviceUrl referencia o serviço HTTP que implementa a API. A API de Gestão reencaminha os pedidos para este endereço. Nos back-ends do Service Fabric, o valor do URL não é utilizado. Pode pôr qualquer valor aqui. Para este artigo, por exemplo "http://servicefabric".
• path é anexado ao URL base do serviço Gestão de API. O URL base é comum a todas as APIs alojadas por uma instância do serviço Gestão de API. A Gestão de API distingue as APIs pelo respetivo sufixo, pelo que cada API tem de ter o seu sufixo exclusivo para um determinado editor.
• O campo protocols determina que protocolos podem ser utilizados para aceder à API. Para este artigo, liste http e https.
• path é um sufixo para a API. Para este artigo, utilize "myapp".

Microsoft.ApiManagement/service/apis/operations

Microsoft.ApiManagement/service/apis/operations Antes de poder utilizar uma API da Gestão de API, é necessário adicionar operações à API. Os clientes externos utilizam uma operação para comunicar com o serviço sem estado ASP.NET Core em execução no cluster do Service Fabric.

Para adicionar uma operação de API de front-end, preencha os valores:

• displayName e description descrevem a operação. Para este artigo, utilize "Valores".
• method especifica o verbo HTTP. Para este artigo, especifique GET.
• urlTemplate é anexado ao URL base da API e identifica uma operação HTTP individual. Para este artigo, utilize /api/values se adicionou o serviço de back-end .NET ou getMessage se adicionou o serviço de back-end Java. Por predefinição, o caminho do URL especificado aqui é o caminho do URL enviado para o serviço de back-end do Service Fabric. Se utilizar aqui o mesmo caminho de URL do seu serviço, como, por exemplo, "/api/values", a operação funciona sem mais modificações. Também pode especificar aqui um caminho de URL diferente daquele que o serviço de back-end do Service Fabric utiliza, caso em que também tem de especificar, mais tarde, uma reescrita de caminho na política da operação.

Microsoft.ApiManagement/service/apis/policies

Microsoft.ApiManagement/service/apis/policies cria uma política de back-end, que vincula todos os elementos. É aqui que vai configurar o serviço de back-end do Service Fabric para o qual os pedidos são encaminhados. Pode aplicar esta política a todas as operações de API. Para obter mais informações, veja Policies overview (Descrição Geral das Políticas).

A configuração do back-end do Service Fabric disponibiliza os controlos de encaminhamento de pedidos seguintes:

• Seleção de instâncias do serviço, mediante a especificação do nome de uma instância do serviço Service Fabric, seja hard-coded (por exemplo, "fabric:/myapp/myservice") ou gerado a partir do pedido HTTP (por exemplo, "fabric:/myapp/users/" + context.Request.MatchedParameters["name"]).
• Resolução de partições mediante a geração de uma chave de partição através de qualquer esquema de partições do Service Fabric.
• Seleção de réplicas para serviços com estado.
• Condições de repetição de resolução que lhe permitem especificar as condições para voltar a resolver uma localização de serviço e reenviar um pedido.

policyContent é o conteúdo XML com escape JSON da política. Para este artigo, crie uma política de back-end para encaminhar pedidos diretamente para o serviço .NET ou Java sem estado implementado anteriormente. Adicione uma política set-backend-service nas políticas de entrada. Substitua o valor sf-service-instance-name por fabric:/ApiApplication/WebApiService, se tiver implementado anteriormente o serviço de back-end .NET, ou por fabric:/EchoServerApplication/EchoServerService, se tiver implementado o serviço Java. backend-id referencia um recurso de back-end; neste caso, o recurso Microsoft.ApiManagement/service/backends definido no modelo apim.json. backend-id também pode referenciar outro recurso de back-end que tenha sido criado com as APIs da Gestão de API. Para este artigo, defina back-end-id para o valor do parâmetro service_fabric_backend_name .

<policies>
  <inbound>
    <base/>
    <set-backend-service
        backend-id="servicefabric"
        sf-service-instance-name="service-name"
        sf-resolve-condition="@(context.LastError?.Reason == "BackendConnectionFailure")" />
  </inbound>
  <backend>
    <base/>
  </backend>
  <outbound>
    <base/>
  </outbound>
</policies>

Para obter um conjunto completo dos atributos de políticas de back-ends do Service Fabric, veja a documentação sobre o back-end da Gestão de API

Definir parâmetros e implementar a Gestão de API

Preencha os parâmetros vazios seguintes em apim.parameters.json da sua implementação.

Parâmetro	Valor
apimInstanceName	sf-apim
apimPublisherEmail	myemail@contosos.com
apimSku	Programador
serviceFabricCertificateName	sfclustertutorialgroup320171031144217
certificatePassword	q6D7nN%6ck@6
serviceFabricCertificateThumbprint	C4C1E541AD512B8065280292A8BA6079C3F26F10
serviceFabricCertificate	<cadeia com codificação base 64>
url_path	/api/values
clusterHttpManagementEndpoint	https://mysfcluster.southcentralus.cloudapp.azure.com:19080
inbound_policy	<Cadeia XML>

certificatePassword e serviceFabricCertificateThumbprint têm de corresponder ao certificado de cluster que foi utilizado para configurar o cluster.

serviceFabricCertificate é o certificado como cadeia com codificação base 64, que pode ser gerada com o script abaixo:

$bytes = [System.IO.File]::ReadAllBytes("C:\mycertificates\sfclustertutorialgroup220171109113527.pfx");
$b64 = [System.Convert]::ToBase64String($bytes);
[System.Io.File]::WriteAllText("C:\mycertificates\sfclustertutorialgroup220171109113527.txt", $b64);

Em inbound_policy, substitua o valor sf-service-instance-name por fabric:/ApiApplication/WebApiService, se tiver implementado anteriormente o serviço de back-end .NET, ou por fabric:/EchoServerApplication/EchoServerService, se tiver implementado o serviço Java. backend-id referencia um recurso de back-end; neste caso, o recurso Microsoft.ApiManagement/service/backends definido no modelo apim.json. backend-id também pode referenciar outro recurso de back-end que tenha sido criado com as APIs da Gestão de API. Para este artigo, defina back-end-id para o valor do parâmetro service_fabric_backend_name .

<policies>
  <inbound>
    <base/>
    <set-backend-service
        backend-id="servicefabric"
        sf-service-instance-name="service-name"
        sf-resolve-condition="@(context.LastError?.Reason == "BackendConnectionFailure")" />
  </inbound>
  <backend>
    <base/>
  </backend>
  <outbound>
    <base/>
  </outbound>
</policies>

Utilize o script abaixo para implementar o modelo do Resource Manager e os ficheiros de parâmetros da Gestão de API:

$groupname = "sfclustertutorialgroup"
$clusterloc="southcentralus"
$templatepath="C:\clustertemplates"

New-AzResourceGroupDeployment -ResourceGroupName $groupname -TemplateFile "$templatepath\network-apim.json" -TemplateParameterFile "$templatepath\network-apim.parameters.json" -Verbose

New-AzResourceGroupDeployment -ResourceGroupName $groupname -TemplateFile "$templatepath\apim.json" -TemplateParameterFile "$templatepath\apim.parameters.json" -Verbose

ResourceGroupName="sfclustertutorialgroup"
az deployment group create --name ApiMgmtNetworkDeployment --resource-group $ResourceGroupName --template-file network-apim.json --parameters @network-apim.parameters.json

az deployment group create --name ApiMgmtDeployment --resource-group $ResourceGroupName --template-file apim.json --parameters @apim.parameters.json

Testar

Agora, pode experimentar enviar um pedido para o serviço de back-end do Service Fabric através da Gestão de API diretamente no portal do Azure.

1. No serviço Gestão de API, selecione API.

2. Na API Service Fabric App que criou nos passos anteriores, selecione o separador Testar e, em seguida, selecione a operação Values.

3. Clique no botão Enviar para enviar um pedido de teste para o serviço de back-end. Deverá ver uma resposta HTTP semelhante a:

   HTTP/1.1 200 OK
   
   Transfer-Encoding: chunked
   
   Content-Type: application/json; charset=utf-8
   
   Vary: Origin
   
   Ocp-Apim-Trace-Location: https://apimgmtstodhwklpry2xgkdj.blob.core.windows.net/apiinspectorcontainer/PWSQOq_FCDjGcaI1rdMn8w2-2?sv=2015-07-08&sr=b&sig=MhQhzk%2FEKzE5odlLXRjyVsgzltWGF8OkNzAKaf0B1P0%3D&se=2018-01-28T01%3A04%3A44Z&sp=r&traceId=9f8f1892121e445ea1ae4d2bc8449ce4
   
   Date: Sat, 27 Jan 2018 01:04:44 GMT
   
   
   ["value1", "value2"]
   

Limpar os recursos

Um cluster é constituído por outros recursos do Azure, além do próprio recurso do cluster. A forma mais simples de eliminar o cluster e todos os recursos que consome é eliminando o grupo de recursos.

Inicie sessão no Azure e selecione o ID da subscrição com o qual pretende remover o cluster. Pode encontrar o ID da subscrição ao iniciar sessão no portal do Azure. Elimine o grupo de recursos e todos os recursos do cluster com o cmdlet Remove-AzResourceGroup.

$ResourceGroupName = "sfclustertutorialgroup"
Remove-AzResourceGroup -Name $ResourceGroupName -Force

ResourceGroupName="sfclustertutorialgroup"
az group delete --name $ResourceGroupName

Passos seguintes

Saiba mais sobre como utilizar Gestão de API.

Também pode utilizar o portal do Azure para criar e gerir back-ends do Service Fabric para Gestão de API.