在 Azure 中将 API 管理与 Service Fabric 集成

项目
05/29/2023

使用 Service Fabric 部署 Azure API 管理是一个高级方案。当需要使用一组丰富的路由规则为后端 Service Fabric 服务发布 API 时，API 管理非常有用。云应用程序通常都需要使用前端网关，为用户、设备或其他应用程序提供同一个入口点。在 Service Fabric 中，网关可以是专为流量入口（如 ASP.NET Core 应用程序、事件中心、IoT 中心或 Azure API 管理）设计的任意无状态服务。

本文演示了如何设置 Azure API 管理与 Service Fabric，以在 Service Fabric 中将流量路由至后端服务。完成后，便已将 API 管理部署到 VNET，并已将 API 操作配置为将流量发送到后端无状态服务。若要详细了解使用 Service Fabric 的 Azure API 管理方案，请参阅概述一文。

注意

建议使用 Azure Az PowerShell 模块与 Azure 交互。请参阅安装 Azure PowerShell 以开始使用。若要了解如何迁移到 Az PowerShell 模块，请参阅将 Azure PowerShell 从 AzureRM 迁移到 Az。

可用性

重要

由于所需的虚拟网络支持，此功能在 API 管理的高级和开发人员层中可用。

必备条件

开始之前：

如果没有 Azure 订阅，请创建一个试用版订阅
安装 Azure PowerShell 或 Azure CLI。
在网络安全组中创建一个安全的 Windows 群集。
如果部署 Windows 群集，请设置 Windows 开发环境。安装 Visual Studio 2019 和 Azure 开发、ASP.NET 和 Web 开发以及 .NET Core 跨平台开发工作负荷。然后设置 .NET 开发环境。

网络拓扑

现在，你在 Azure 上拥有了一个安全的 Windows 群集，可以在子网和专为 API 管理指定的 NSG 中将 API 管理部署到虚拟网络 (VNET)。对于本文，API 管理资源管理器模板预配置为使用你在 Windows 群集教程中设置的 VNET、子网和 NSG 的名称。本文将以下拓扑部署到 Azure，其中，API 管理和 Service Fabric 位于同一虚拟网络的子网中：

Picture caption

执行 Azure 命令之前，登录到你的 Azure 帐户并选择你的订阅。

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

az cloud set -n AzureChinaCloud
az login
az account set --subscription <guid>

部署 Service Fabric 后端服务

在配置 API 管理以将流量路由到 Service Fabric 后端服务前，首先需要一个运行的服务来接受请求。

使用默认的 Web API 项目模板创建一个基本的无状态 ASP.NET Core 可靠服务。这可为服务创建一个 HTTP 终结点，可通过 Azure API 管理公开此终结点。

以管理员身份启动 Visual Studio 并创建 ASP.NET Core 服务：

在 Visual Studio 中，选择“文件”->“新建项目”。
选择“云”下的 Service Fabric 应用程序模板并将其命名为“ApiApplication” 。
选择无状态 ASP.NET Core 服务模板并将项目命名为“WebApiService” 。
选择 Web API ASP.NET Core 2.1 项目模板。
创建项目后，打开 PackageRoot\ServiceManifest.xml 并从终结点资源配置中删除 Port 属性：
```
<Resources>
  <Endpoints>
    <Endpoint Protocol="http" Name="ServiceEndpoint" Type="Input" />
  </Endpoints>
</Resources>
```
删除端口允许 Service Fabric 从应用程序端口范围动态指定一个端口，可通过群集资源管理器模板中的网络安全组将其打开，从而允许流量从 API 管理流向该端口。
可在本地于 Visual Studio 中按下 F5 来验证 Web API。

打开 Service Fabric Explorer 并深入了解 ASP.NET Core 服务的特定实例，以查看服务正在侦听的基址。将 /api/values 添加到基址，然后在浏览器中打开，这在 Web API 模板的 ValuesController 上调用 Get 方法。它会返回模板提供的默认响应，即包含两个字符串的 JSON 数组：
```
["value1", "value2"]`
```
这是你通过 Azure 中的 API 管理公开的终结点。
最后，将应用程序部署到 Azure 中的群集。在 Visual Studio 中，右键单击“应用程序”项目，然后选择“发布” 。提供群集终结点（例如，mycluster.chinanorth.cloudapp.chinacloudapi.cn:19000），将应用程序部署到 Azure 中的 Service Fabric 群集。

名为 fabric:/ApiApplication/WebApiService 的 ASP.NET Core 无状态服务现在应在 Azure 的 Service Fabric 群集中运行。

下载资源管理器模板并了解其相关信息

下载并保存以下资源管理器模板和参数文件：

network-apim.json 模板将新的子网和网络安全组部署在已部署的 Service Fabric 群集所在的虚拟网络中。

以下部分介绍由 apim.json 模板定义的资源。有关详细信息，请访问每个部分中模板引用文档的链接。文本稍后部分设置了 apim.parameters.json 参数文件中定义的可配置参数。

Microsoft.ApiManagement/service

Microsoft.ApiManagement/service 描述了 API 管理服务实例：名称、SKU 或层级、资源组位置、发布者信息和虚拟网络。

Microsoft.ApiManagement/service/certificates

Microsoft.ApiManagement/service/certificates 用于配置 API 管理安全性。 API 管理必须使用有权访问群集的客户端证书对用于服务发现的 Service Fabric 群集进行身份验证。本文使用之前在创建 Windows 群集时指定的同一证书，该证书默认可用于访问群集。

本文对客户端身份验证和群集节点到节点安全性使用相同的证书。如果你配置了一个单独的客户端证书，则可以使用它来访问 Service Fabric 群集。提供创建 Service Fabric 群集时指定的群集证书私钥文件 (.pfx) 的“名称”、“密码”和“数据”（base-64 编码字符串）。

Microsoft.ApiManagement/service/backends

Microsoft.ApiManagement/service/backends 描述了流量转发到的后端服务。

对于 Service Fabric 后端，后端是 Service Fabric 群集，而不是特定的 Service Fabric 服务。这允许单个策略路由到群集中的多个服务。如果后端策略中未指定任何服务名称，那么此处的 url 字段是群集中一个服务的完全限定的服务名称，默认情况下所有请求都路由到该服务。如果你不打算获取回退服务，可以使用一个假的服务名称，如“fabric:/fake/service”。 resourceId 指定群集管理终结点。 clientCertificateThumbprint 和 serverCertificateThumbprints 标识用于对群集进行身份验证的证书。

Microsoft.ApiManagement/service/products

Microsoft.ApiManagement/service/products 用于创建产品。在 Azure API 管理中，产品包含一个或多个 API 以及使用配额和使用条款。一旦产品发布，开发人员可以订阅该产品，并开始使用产品的 API。

为产品输入描述性“displayName”和“description” 。对于本文，订阅是必需的，但不需要管理员批准订阅。产品“state”为“已发布”，并对订阅者可见。

Microsoft.ApiManagement/service/apis

Microsoft.ApiManagement/service/apis 用于创建 API。 API 管理中的 API 表示一组可由客户端应用程序调用的操作。一旦添加操作，该 API 添加到某一产品并可以发布。发布 API 后，它可供开发人员订阅和使用。

“displayName”可以是 API 的任意名称。对于本文，请使用“Service Fabric App”。
“name”为 API 提供一个唯一且有描述性的名称，例如“service-fabric-app” 。它显示在开发人员和发布者门户中。
“serviceUrl”引用实现 API 的 HTTP 服务。 API 管理将请求转发到此地址。对于 Service Fabric 后端，不使用此 URL 值。你可以在此处设置任何值。对于本文，例如“http://servicefabric"”。
“path”附加到 API 管理服务的基础 URL 。基础 URL 是常见的由 API 管理服务实例托管的所有 API。 API 管理通过其后缀区分 API，因此后缀对给定发布者上的每个 API 必须唯一。
“protocols”确定可用于访问 API 的协议。对于本文，列出 http 和 https。
“path”是 API 的后缀。对于本文，请使用“myapp”。

Microsoft.ApiManagement/service/apis/operations

Microsoft.ApiManagement/service/apis/operations 在使用 API 管理中的 API 前，必须向 API 添加操作。外部客户端使用操作与 Service Fabric 群集中运行的 ASP.NET Core 无状态服务进行通信。

要添加前端 API 操作，请填写以下值：

“displayName”和“description”描述操作。对于本文，请使用“Values”。
“method”指定 HTTP 谓词。对于本文，请指定 GET。
“urlTemplate”附加到 API 的基础 URL，并标识单个 HTTP 操作。对于本文，如果添加了.NET 后端服务，请使用 /api/values，如果添加了 Java 后端服务，请使用 getMessage。默认情况下，在此处指定的 URL 路径是发送到后端 Service Fabric 服务的 URL 路径。如果在此处使用服务所用的相同 URL 路径（例如“/api/values”），则无需进一步修改即可正常执行该操作。还可以在此处指定一个与后端 Service Fabric 服务使用的 URL 路径不同的 URL 路径，这种情况下，还需要在以后的操作策略中指定路径重写。

Microsoft.ApiManagement/service/apis/policies

Microsoft.ApiManagement/service/apis/policies 创建将所有内容联系在一起的后端策略。你可以在其中配置将请求路由到的后端 Service Fabric 服务。可以将此策略应用到任何 API 操作。有关详细信息，请参阅策略概述。

Service Fabric 的后端配置提供以下请求路由控件：

服务实例选择，方法是指定硬编码的（例如，"fabric:/myapp/myservice"）或从 HTTP 请求中生成的（例如，"fabric:/myapp/users/" + context.Request.MatchedParameters["name"]）Service Fabric 服务实例名称。
分区解析，方法是使用任何 Service Fabric 分区方案生成分区键。
用于有状态服务的副本选择。
解析重试条件，允许你指定用于重新解析服务位置并重新发送请求的条件。

“policyContent”是策略的 JSON 转义 XML 内容。对于本文，请创建一个将请求直接路由到以前部署的 .NET 或 Java 无状态服务的后端策略。在入站策略下添加 set-backend-service 策略。如果之前部署了 .NET 后端服务，则将 sf-service-instance-name 值替换为 fabric:/ApiApplication/WebApiService，如果部署了 Java 服务，则替换为 fabric:/EchoServerApplication/EchoServerService。 backend-id 引用一个后端资源，在此示例中为在 apim.json 模板中定义的 Microsoft.ApiManagement/service/backends 资源。 backend-id 也可引用使用 API 管理 API 创建的另一后端资源。对于本文，请将 backend-id 设置为 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>

有关完整的 Service Fabric 后端策略属性，请参阅 API 管理后端文档

设置参数和部署 API 管理

在部署的 apim.parameters.json 中填写以下空参数。

参数	值
apimInstanceName	sf-apim
apimPublisherEmail	myemail@contosos.com
apimSku	开发人员
serviceFabricCertificateName	sfclustertutorialgroup320171031144217
certificatePassword	q6D7nN%6ck@6
serviceFabricCertificateThumbprint	C4C1E541AD512B8065280292A8BA6079C3F26F10
serviceFabricCertificate	<base-64 编码字符串>
url_path	/api/values
clusterHttpManagementEndpoint	`https://mysfcluster.chinanorth.cloudapp.chinacloudapi.cn:19080`
inbound_policy	<XML 字符串>

“certificatePassword”和“serviceFabricCertificateThumbprint”必须与用于设置群集的群集证书匹配。

“serviceFabricCertificate”是 base-64 编码字符串形式的证书，可以使用以下脚本生成：

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

在 inbound_policy 中，如果之前部署了 .NET 后端服务，则将 sf-service-instance-name 值替换为 fabric:/ApiApplication/WebApiService，如果部署了 Java 服务，则替换为 fabric:/EchoServerApplication/EchoServerService。 backend-id 引用一个后端资源，在此示例中为在 apim.json 模板中定义的 Microsoft.ApiManagement/service/backends 资源。 backend-id 也可引用使用 API 管理 API 创建的另一后端资源。对于本文，请将 backend-id 设置为 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>

使用以下脚本为 API 管理部署资源管理器模板和参数文件：

$groupname = "sfclustertutorialgroup"
$clusterloc="chinanorth"
$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

测试

现在可以尝试直接从 Azure 门户通过 API 管理将请求发送到 Service Fabric 中的后端服务。

在 API 管理服务中，选择“API” 。
在于之前的步骤中创建的“Service Fabric 应用” API 中，选择“测试” 选项卡，然后选择“值” 操作。

单击“发送” 按钮，将测试请求发送到后端服务。应该会看到类似于以下内容的 HTTP 响应：

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.chinacloudapi.cn/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"]

清理资源

群集由群集资源本身以及其他 Azure 资源组成。若要删除群集及其占用的所有资源，最简单的方式是删除资源组。

登录到 Azure，选择要删除群集的订阅 ID。可通过登录到 Azure 门户查找订阅 ID。使用 Remove-AzResourceGroup cmdlet 删除资源组和所有群集资源。

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

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

后续步骤

详细了解如何使用 API 管理。

还可使用 Azure 门户为 API 管理创建和管理 Service Fabric 后端。