全部产品
Search
文档中心

API 网关:使用自定义域名调用API

更新时间:Nov 13, 2024

使用API网关对外提供服务时,您可以使用自己拥有的域名来开放对外提供服务的能力,本文主要介绍如何将自己的域名绑定到API网关上,让客户端使用域名来调用其开放的API。

概述

域名与分组、API之间的关系

  • 用户需要将自己拥有的域名绑定到API网关的分组上,建立域名与分组之间的映射关系。

  • API网关在接收到客户端发出的HTTP请求时,根据HTTP请求中的域名来定位到这个请求所属的API分组,再通过HTTP方法和路径确定唯一的API。

重要

API网关为每个分组默认提供了公网二级域名,如果客户端直接调用API分组提供的公网二级域名,将会受到每天1000次调用的限制(海外Region及中国香港限制100次/天)。并且调用API网关提供的公网二级域名时,所有应答都会默认返回一个"Content-Disposition: attachment; filename=ApiResponseForInnerDomain"的头。在您正式生产环境开放API时,需要为API分组绑定独立域名才可正常使用,不受此项限制。

域名备案

在中国内地Region绑定独立域名到分组上的前提是独立域名需要在阿里云备案或者在阿里云备案接入,海外Region不需要域名备案。

说明

绑定内网类型域名不需要进行备案。

域名所有权确认

域名在API网关上没有被实例且同BasePath的分组绑定,并且不和其他已经绑定的泛域名冲突,才能成功绑定。域名的所有权验证有两种,您只需要满足任一条件即可:

  1. 用户将域名通过CNAME的方式解析到API网关分组上的二级域名上。

  2. 用户在绑定的域名上增加一条记录类型为TXT的解析,记录名称为“分组ID.域名”,记录值为“apigateway-domain-verfication=公网分组二级域名”。

    例如:

    一个分组,ID为b7eb2f79e64f4431b08bbb948ed2567e,二级域名为b7eb2f79e64f4431b08bbb948ed2567e-cn-hangzhou.alicloudapi.com,绑定的域名为单域名youdomain.com或者泛域名*.yourdomain,用户需要增加一条域名记录,类型为TXT,主机记录(RR)为b7eb2f79e64f4431b08bbb948ed2567e.yourdomain.com,记录值为apigateway-domain-verfication=b7eb2f79e64f4431b08bbb948ed2567e-cn-hangzhou.alicloudapi.com

重要
  • 绑定内网类型域名将不进行域名所有权确认。

  • 如果不将域名通过CNAME绑定到API网关,客户端通过域名请求时,无法请求到API网关。

  • 不同的分组绑定同一域名时需注意:

    • 分组在同一实例时,BasePath必须是不同的,BasePath长度最大为300字节。

    • 分组在不同的实例时,客户端请求API需要自己配置DNS来指定请求的实例。

方案概览

将自己的公网/内网域名绑定到API网关上,可以通过单域名绑定泛域名绑定方式来实现,主要分为以下步骤:

  1. 域名解析:将公网/内网域名通过CNAME方式或者TXT解析方式解析到API网关分组上提供的二级域名。

    • 公网域名解析:将您的公网域名通过云解析DNS完成与API网关分组的公网二级域名映射。

    • 内网域名解析:将您的内网域名通过云解析DNS完成与API网关分组的内网二级域名映射。

  2. 域名绑定:在API网关控制台的分组详情页面将域名绑定到对应的分组上。

  3. (可选)设置分组默认域名:当分组下绑定了多个域名并且多个域名同时支持HTTPS调用时,您需要设置默认域名。

单域名绑定

域名解析

公网域名解析

  1. 登录API网关控制台,在左侧导航栏选择API管理 > 分组管理并在页面选择地域。

  2. 分组列表页面,单击目标分组,进入分组详情页面,在基本信息处找到这个分组对应的API网关提供的公网二级域名。

  3. 登录云解析DNS控制台,在左侧导航栏选择公网DNS解析 > 权威域名解析,在权威域名解析页面选择权威域名栏。单击要解析的域名,进入解析设置栏。

  4. 解析设置栏,单击添加记录,在添加记录弹框中选择记录类型为CNAME,主机记录填写域名的前缀,记录值填写获取到的公网二级域名,单击确定即可完成。

    image

内网域名解析

  1. 登录API网关控制台,在左侧导航栏选择API管理 > 分组管理并在页面选择地域。

  2. 分组列表页面,单击目标分组,进入分组详情页面,在基本信息处找到这个分组对应的API网关提供的内网VPC域名。

  3. 登录云解析 DNS控制台,在左侧导航栏选择内网DNS解析 (PrivateZone) ,在内网DNS解析 (PrivateZone)页面,选择页面右上角管理配置模式用户域名栏单击添加域名(Zone)。

  4. 添加内置权威域名 (Zone)弹框中,输入内置权威域名 (Zone)名称和选择阿里云VPC内网,单击确定

    添加zone

    说明

    此处的内置权威域名 (Zone)填写API网关分组所要绑定的自定义的域名(私有域名),即您想要在VPC环境内专门为其设置内网DNS解析 (PrivateZone)的域名名称。

  5. 单击添加的内置权威域名 (Zone)名称,进入解析记录页面,单击添加记录,为该私有域名添加CNAME解析记录,在添加记录弹框中记录类型选择CNAME,主机记录填写域名前缀,记录值填写获取到的内网VPC域名,单击确定

    image

说明
  • 添加的内置权威域名 (Zone)关联VPC后,在被关联VPC内的ECS上,您的私有域名将按照内网DNS解析 (PrivateZone)中的解析记录来解析,其公网解析记录则会被覆盖。

  • VPC环境外,该内置权威域名(Zone)的公网解析记录不受影响,通过为内置权威域名(Zone)添加内网DNS解析(PrivateZone)中的解析记录,可以防止记录为空的内置权威域名(Zone)将需要使用的公网解析给覆盖掉,造成异常。更多详情可参考开通PrivateZone文档。

域名绑定

  1. 登录API网关控制台,在左侧导航栏选择API管理 > 分组管理并在页面选择地域。

  2. 分组列表页面,单击需要绑定域名的分组,进入分组详情页面,在页面独立域名处单击绑定域名按钮。

  3. 域名绑定弹框中,配置参数如下并单击确定

    配置项目

    描述

    域名

    填写要绑定的域名。

    环境

    指的是域名绑定的环境,分别如下:

    • 指定为测试环境(TEST) :仅支持调用测试环境API。

    • 指定为预发环境(PRE ):仅支持调用预发环境API。

    • 指定为线上环境(RELEASE):仅支持调用线上环境API。

    • 默认(使用X-Ca-Stage确定环境):以上三种环境均可调用,调用时在请求的Header添加X-Ca-Stage参数指定调用的环境。

    网络类型

    公网类型仅支持通过公网调用API。内网类型仅支持通过内网调用API。

说明
  • 内网类型域名不进行域名所有权校验,若与实例内其他分组绑定域名冲突,将绑定失败。

  • 域名绑定成功后,不支持修改网络类型,若配置有误,可以删除域名重新绑定。

域名绑定常见问题

域名绑定失败,需要怎样处理?

  • 要绑定的域名已经在API网关被当前用户绑定到了当前实例的其他分组上,或者和当前用户已经绑定的其他域名有范围冲突(指泛域名和单域名之间存在的覆盖关系),此时用户需要从原来的分组上解绑该自定义域名,才能重新在当前分组上绑定该域名。

  • 要绑定的域名已经在API网关被其他用户绑定到了该用户名下的分组上,或者和当前用户已经绑定的其他域名有范围冲突(指泛域名和单域名之间存在的覆盖关系),此时用户必须通过域名所有权确认中提到的方法证明此自定义域名的所有权才能成功绑定。

调用验证

绑定成功后,我们就可以随意使用绑定的域名来访问这个分组下的API了,假如您有一个API,可以通过简单的curl来访问:

curl http://yourdomain.com/apipath -i
HTTP/1.1 200 OK
Date: Mon, 23 Mar 2020 08:40:01 GMT
Connection: keep-alive
Keep-Alive: timeout=25
Server: Jetty(7.2.2.v20101205)
X-Ca-Request-Id: E2B8CBAB-D6EF-4576-838F-44DDC1A6B20D
重要

若绑定的是内网域名,需在您已关联的VPC内进行测试。

泛域名绑定

API网关目前已经支持了泛域名绑定,您可以将泛域名解析到API网关的公网二级域名,之后在控制台上将对应的泛域名绑定至API分组,就可以通过泛域名来调用API网关上托管的对应分组下的所有API。

泛域名绑定实现

泛域名的绑定和单域名绑定的流程是大体一致的,假如您是abc.com这个域名的拥有者,您想将abc.com这个域名的所有子域名(比如1.abc.com,2.abc.com)都指向API网关对外提供服务,现在可以通过以下步骤实现这个能力:

  1. 在您的域名解析管理平台将*.abc.com通过CNAME的方式解析到API网关分组的公网二级域名上。

  2. 在API网关控制台的分组详情页面上,将*.abc.com绑定到对应的分组上。

说明

仅VPC实例支持泛域名能力。一旦绑定成功后,客户端就可以通过abc.com这个域名的所有子域名(比如1.abc.com,2.abc.com)来访问所绑定的分组下所有API了,比如对应分组下有个API可以通过Get方法匿名访问,那么在绑定了*.abc.com这个泛域名之后,就可以通过1.abc.com,2.abc.com等域名同时来访问了。

泛域名绑定注意事项

  1. 绑定泛域名的时候必须要验证域名所有权,具体验证方法参见域名所有权的描述。

  2. 泛域名绑定成功之后,必须在分组详情页面设置对应的泛域名模板,泛域名的调用才会生效。

说明

泛域名模板主要是为了配置域名参数所用,也就是泛域名中的可变字段实际可以作为一个参数传给后端服务的。

设置分组默认域名

API网关允许用户上传域名对应的HTTPS证书,并对外提供安全级别更高的HTTPS调用能力。在分组下绑定了多个域名时,并且多个域名同时支持HTTPS调用时,需要设置默认域名,才能在接收到不支持SNI客户端发送的SSL握手请求时返回默认域名证书,否则API网关会随机返回域名证书。设置分组默认域名仅对专享实例生效,共享实例/Serverless实例默认不支持默认证书,不支持SNI的低版本客户端进行HTTPS访问时可能会产生证书混淆的问题。

重要

专享实例上如果绑定了多个分组,只能加载第一个分组的默认域名,其他设置无效。