Integrar a API Management com o Service Fabric no Azure

Implantar o Gerenciamento de API do Azure com o Service Fabric é um cenário avançado. O Gerenciamento de API é útil quando você precisa publicar APIs com um conjunto avançado de regras de roteamento para seus serviços 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, um gateway pode ser qualquer serviço sem estado concebido para receção de tráfego, como uma aplicação ASP.NET Core, Hub de Eventos, Hub IoT ou Gestão de API do Azure.

Este artigo mostra como configurar o Gerenciamento de API do Azure com o Service Fabric para rotear o tráfego para um serviço back-end no Service Fabric. Quando terminar, você implantou o Gerenciamento de API em uma VNET, configurou uma operação de API para enviar tráfego para serviços sem estado de back-end. Para saber mais sobre cenários de Gerenciamento de API do Azure com o Service Fabric, consulte o artigo de visão geral .

Disponibilidade

Pré-requisitos

Antes de começar:

• Se não tiver uma subscrição do Azure, crie uma conta gratuita
• Instale o Azure PowerShell ou a CLI do Azure.
• Crie um cluster seguro do Windows em um grupo de segurança de rede.
• Se você implantar um cluster do Windows, configure um ambiente de desenvolvimento do Windows. Instale o Visual Studio 2019 e as cargas de trabalho de desenvolvimento de plataforma cruzada do Azure, desenvolvimento ASP.NET e Web e .NET Core . Em seguida, configure um ambiente de desenvolvimento .NET.

Topologia de rede

Agora que você tem um cluster seguro do Windows no Azure, implante o Gerenciamento de API na rede virtual (VNET) na sub-rede e no NSG designado para Gerenciamento de API. Para este artigo, o modelo do Gerenciador de Recursos de Gerenciamento de API é pré-configurado para usar os nomes da VNET, sub-rede e NSG que você configurou no tutorial de cluster do Windows Este artigo implanta a seguinte topologia no Azure na qual o Gerenciamento de API e o Service Fabric estão em sub-redes da mesma Rede Virtual:

Entre no Azure e selecione sua assinatura

Entre em sua conta do Azure, selecione sua assinatura antes de executar comandos do Azure.

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

az login
az account set --subscription <guid>

Implantar um serviço back-end do Service Fabric

Antes de configurar o Gerenciamento de API para rotear o tráfego para um serviço back-end do Service Fabric, primeiro você precisa de um serviço em execução para aceitar solicitações.

Crie um Serviço Fiável ASP.NET Core sem estado básico usando o modelo de projeto de Web API padrão. Isso cria um ponto de extremidade HTTP para seu serviço, que você expõe por meio do Gerenciamento de API do Azure.

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

1. No Visual Studio, selecione Arquivo -> Novo Projeto.

2. Selecione o modelo de Aplicativo do Service Fabric em Nuvem e nomeie-o como "ApiApplication".

3. Selecione o modelo de serviço ASP.NET Core sem estado e nomeie o projeto como "WebApiService".

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

5. Depois que o projeto for criado, abra PackageRoot\ServiceManifest.xml e remova o Port atributo da configuração de recursos 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 uma porta dinamicamente a partir do intervalo de portas do aplicativo, aberta por meio do Grupo de Segurança de Rede no modelo Gerenciador de Recursos de Cluster, permitindo que o tráfego flua para ela a partir do Gerenciamento de API.

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

   Abra o Service Fabric Explorer e faça uma busca detalhada em uma instância específica do serviço ASP.NET Core para ver o endereço base no qual o serviço está escutando. Adicione /api/values ao endereço base e abra-o em um navegador, que invoca o método Get no ValuesController no modelo de API Web. Ele retorna a resposta padrão fornecida pelo modelo, uma matriz JSON que contém duas cadeias de caracteres:

   ["value1", "value2"]`
   

   Este é o ponto de extremidade que você expõe por meio do Gerenciamento de API no Azure.

7. Por fim, implante o aplicativo em seu cluster no Azure. No Visual Studio, clique com o botão direito do mouse no projeto Application e selecione Publicar. Forneça o seu ponto de extremidade de cluster (por exemplo, mycluster.southcentralus.cloudapp.azure.com:19000) para implantar a aplicação no seu cluster do Service Fabric no Azure.

Um serviço sem estado do ASP.NET Core nomeado fabric:/ApiApplication/WebApiService agora deve estar em execução em seu cluster do Service Fabric no Azure.

Transfira e compreenda os modelos do Resource Manager

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

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

O modelo network-apim.json implanta uma nova sub-rede e um novo grupo de segurança de rede na rede virtual onde o cluster do Service Fabric está implantado.

As seções a seguir descrevem os recursos que estão sendo definidos pelo modelo apim.json . Para obter mais informações, siga os links para a documentação de referência do modelo em cada seção. Os parâmetros configuráveis definidos no arquivo de parâmetrosapim.parameters.json são definidos posteriormente neste artigo.

Microsoft.ApiManagement/service

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

Microsoft.ApiManagement/serviço/certificados

Microsoft.ApiManagement/service/certificates configura a segurança do Gerenciamento de API. O Gerenciamento de API deve autenticar-se com seu cluster do Service Fabric para descoberta de serviço usando um certificado de cliente que tenha acesso ao cluster. Este artigo usa o mesmo certificado especificado anteriormente ao criar o cluster do Windows, que por padrão pode ser usado para acessar o cluster.

Este artigo usa o mesmo certificado para autenticação de cliente e segurança nó-a-nó de cluster. Você pode usar um certificado de cliente separado se tiver um configurado para acessar seu cluster do Service Fabric. Forneça o nome, a senha e os dados (cadeia de caracteres codificada em base 64) do arquivo de chave privada (.pfx) do certificado de cluster especificado ao criar 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 é encaminhado.

No caso dos back-ends do Service Fabric, o cluster do Service Fabric é o back-end em vez de um serviço específico do Service Fabric. Isso permite que uma única política roteie para mais de um serviço no cluster. O campo url aqui é um nome de serviço totalmente qualificado de um serviço em seu cluster para o qual todas as solicitações são roteadas por padrão se nenhum nome de serviço for especificado em uma política de back-end. Você pode usar um nome de serviço falso, como "fabric:/fake/service" se não pretende ter um serviço de fallback. resourceId especifica o endpoint de gestão de cluster. clientCertificateThumbprint e serverCertificateThumbprints identificam certificados usados para autenticação com o cluster.

Microsoft.ApiManagement/serviço/produtos

Microsoft.ApiManagement/service/products cria um produto. No Gerenciamento de API do Azure, um produto contém uma ou mais APIs, bem como uma cota de uso e os termos de uso. Depois que um produto é publicado, os desenvolvedores podem assiná-lo e começar a usar as APIs do produto.

Insira um displayName descritivo e uma descrição para o produto. Para este artigo, é necessária uma subscrição, mas não é necessária a aprovação da subscrição por um administrador. Este estado do produto é "publicado" e é visível para os subscritores.

Microsoft.ApiManagement/service/apis

Microsoft.ApiManagement/service/apis cria uma API. Uma API no Gerenciamento de API representa um conjunto de operações que podem ser invocadas por aplicativos cliente. Depois que as operações são adicionadas, a API é adicionada a um produto e pode ser publicada. Depois que uma API é publicada, ela pode ser assinada e usada por desenvolvedores.

• displayName pode ser qualquer nome para sua API. Para este artigo, use "Aplicativo do Service Fabric".
• name fornece um nome exclusivo e descritivo para a API, como "service-fabric-app". É exibido nos portais do desenvolvedor e do publicador.
• serviceUrl faz referência ao serviço HTTP que implementa a API. O gerenciamento de API encaminha solicitações para esse endereço. Para back-ends do Service Fabric, esse valor de URL não é usado. Você pode colocar qualquer valor aqui. Para este artigo, por exemplo "http://servicefabric".
• path é anexado à URL base do serviço de gerenciamento de API. A URL base é comum para todas as APIs hospedadas por uma instância de serviço de Gerenciamento de API. O Gerenciamento de API distingue as APIs por seu sufixo e, portanto, o sufixo deve ser exclusivo para cada API de um determinado editor.
• protocolos determinam quais protocolos podem ser usados para acessar a API. Para este artigo, liste http e https.
• path é um sufixo para a API. Para este artigo, use "myapp".

Microsoft.ApiManagement/service/apis/operations

Microsoft.ApiManagement/service/apis/operations Antes que uma API no Gerenciamento de API possa ser usada, as operações devem ser adicionadas à API. Os clientes externos usam uma operação para comunicar-se com o serviço sem estado ASP.NET Core em execução no cluster do Service Fabric.

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

• displayName e description descrevem a operação. Para este artigo, use "Valores".
• método especifica o verbo HTTP. Para este artigo, especifique GET.
• urlTemplate é anexado à URL base da API e identifica uma única operação HTTP. Para este artigo, use /api/values se você adicionou o serviço de back-end .NET ou getMessage se adicionou o serviço de back-end Java. Por padrão, o caminho de URL especificado aqui é o caminho de URL enviado para o serviço de back-end do Service Fabric. Se você usar o mesmo caminho de URL aqui que seu serviço usa, como "/api/values", a operação funcionará sem mais modificações. Você também pode especificar um caminho de URL aqui que seja diferente do caminho de URL usado pelo serviço de back-end do Service Fabric, caso em que você também precisará especificar um caminho reescrito em sua política de operação posteriormente.

Microsoft.ApiManagement/service/apis/policies

Microsoft.ApiManagement/service/apis/policies cria uma política de back-end, que une tudo. É aqui que você configura o serviço de back-end do Service Fabric para o qual as solicitações são roteadas. Você pode aplicar essa política a qualquer operação de API. Para obter mais informações, consulte Visão geral de políticas.

A configuração de back-end do Service Fabric fornece os seguintes controles de roteamento de solicitação:

• Seleção de instância de serviço especificando um nome de instância de serviço do Service Fabric, codificado (por exemplo, "fabric:/myapp/myservice") ou gerado a partir da solicitação HTTP (por exemplo, "fabric:/myapp/users/" + context.Request.MatchedParameters["name"]).
• Resolução de partições gerando uma chave de partição usando qualquer esquema de particionamento do Service Fabric.
• Seleção de réplicas para serviços com estado.
• Condições de repetição de resolução que permitem especificar as condições para resolver novamente um local de serviço e reenviar uma solicitação.

policyContent é o conteúdo XML com escape de Json da política. Para este artigo, crie uma política de back-end para rotear solicitações diretamente para o serviço sem estado .NET ou Java implantado anteriormente. Adicione uma política sob as políticas de entrada set-backend-service. Substitua o valor sf-service-instance-name por fabric:/ApiApplication/WebApiService se você implantou anteriormente o serviço de back-end .NET ou se implantou fabric:/EchoServerApplication/EchoServerService o serviço Java. backend-id faz referência a um recurso de back-end, neste caso o Microsoft.ApiManagement/service/backends recurso definido no modelo apim.json . backend-id também pode fazer referência a outro recurso de back-end criado usando as APIs de gerenciamento de API. Para este artigo, defina backend-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 de atributos de política de back-end do Service Fabric, consulte a documentação de back-end do Gerenciamento de API

Definir parâmetros e implantar o Gerenciamento de API

Preencha os seguintes parâmetros vazios no apim.parameters.json para a sua instalação.

certificatePassword e serviceFabricCertificateThumbprint devem corresponder ao certificado de cluster usado para configurar o cluster.

serviceFabricCertificate é o certificado como uma cadeia de caracteres codificada em base 64, que pode ser gerada usando o seguinte script:

$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 você implantou anteriormente o serviço de back-end .NET ou se implantou fabric:/EchoServerApplication/EchoServerService o serviço Java. backend-id faz referência a um recurso de back-end, neste caso o Microsoft.ApiManagement/service/backends recurso definido no modelo apim.json . backend-id também pode fazer referência a outro recurso de back-end criado usando as APIs de gerenciamento de API. Para este artigo, defina backend-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>

Use o script a seguir para implantar o modelo do Gerenciador de Recursos e os arquivos de parâmetro para o Gerenciamento 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

Teste-o

Agora você pode tentar enviar uma solicitação para seu serviço back-end no Service Fabric por meio do Gerenciamento de API diretamente do portal do Azure.

1. No serviço Gerenciamento de API, selecione API.

2. Na API do Aplicativo do Service Fabric criada nas etapas anteriores, selecione a guia Teste e, em seguida, a operação Valores .

3. Clique no botão Enviar para enviar uma solicitação de teste para o serviço de back-end. Você deve 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 recursos

Um cluster é composto por outros recursos do Azure, além do próprio recurso de cluster. A maneira mais simples de excluir o cluster e todos os recursos que ele consome é excluir o grupo de recursos.

Entre no Azure e selecione a ID de assinatura com a qual você deseja remover o cluster. Pode encontrar o seu ID de subscrição iniciando sessão no portal do Azure. Exclua o grupo de recursos e todos os recursos de cluster usando o cmdletRemove-AzResourceGroup.

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

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

Próximos passos

Saiba mais sobre como usar o Gerenciamento de API.

Você também pode usar o portal do Azure para criar e gerenciar back-ends do Service Fabric para Gerenciamento de API.