Azure API Management网站facade：是否需为每个数据页面扩展OpenAPI定义？

不需要给第三方可能访问的每个数据页面都添加独立API操作，通过通配符路径的通用API定义+APIM的路由转发、全局策略，可以一次性覆盖所有数据页面的访问需求，具体实现如下：

1. 简化OpenAPI定义，使用通配符路径 #

只需要定义一个包含通配符参数的通用GET操作，覆盖所有数据页面路径。示例OpenAPI片段：

openapi: 3.0.0
info:
  title: 地图数据API
  version: 1.0.0
paths:
  /maps/data/{path}:
    get:
      summary: 获取任意地图数据页面
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
          description: 内部网站的地图数据页面相对路径（比如regions/asia、points/landmarks）
      security:
        - OAuth2: []
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/{你的租户ID}/oauth2/v2.0/token
          scopes:
            map_data.read: 读取地图数据权限

2. 配置APIM全局策略 #

把Validate-JWT策略放在API级别（而非单个操作），同时配置路由转发，确保请求能正确转到内部网站的对应页面。示例APIM策略：

<policies>
    <inbound>
        <!-- 全局验证JWT令牌，所有匹配通配符路径的请求都会触发 -->
        <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="令牌无效或缺失">
            <openid-config url="https://login.microsoftonline.com/{你的租户ID}/v2.0/.well-known/openid-configuration" />
            <required-claims>
                <claim name="aud">
                    <value>{你的API客户端ID}</value>
                </claim>
                <claim name="scp">
                    <value>map_data.read</value>
                </claim>
            </required-claims>
        </validate-jwt>

        <!-- 重写URI，保留通配符部分的路径，转发到内部网站 -->
        <rewrite-uri template="/{path}" copy-unmatched-params="true" />

        <!-- 指定内部网站的后端地址 -->
        <set-backend-service base-url="https://你的内部地图网站域名" />
    </inbound>
    <backend>
        <forward-request />
    </backend>
    <outbound>
        <return-response />
    </outbound>
    <on-error>
        <return-response />
    </on-error>
</policies>

3. 可选：细粒度权限控制（按需添加） #

如果需要对特定数据页面做权限限制（比如敏感数据只允许管理员访问），可以在inbound策略里加入条件判断：

<choose>
    <when condition="@(context.Request.Url.Path.Contains("/sensitive-data"))">
        <validate-jwt header-name="Authorization" failed-validation-httpcode="403" failed-validation-error-message="无敏感数据访问权限">
            <openid-config url="https://login.microsoftonline.com/{你的租户ID}/v2.0/.well-known/openid-configuration" />
            <required-claims>
                <claim name="roles">
                    <value>map_admin</value>
                </claim>
            </required-claims>
        </validate-jwt>
    </when>
</choose>

实际调用示例 #

第三方只需要按照这个格式请求即可：
GET https://你的APIM域名/maps/data/regions/asia
APIM会自动验证JWT，然后转发到内部网站的https://你的内部地图网站域名/regions/asia，返回对应数据。

内容的提问来源于stack exchange，提问作者Rob Bowman