全部产品
Search
文档中心

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

更新时间:Mar 05, 2024

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

1. 概述

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

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

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

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

1.2 域名备案

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

说明

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

1.3 域名所有权确认

域名在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来指定请求的实例。

2.单域名绑定

将用户自己的单域名绑定到API分组需要以下两个步骤:

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

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

2.1 域名解析

2.1.1 公网域名解析

1. 在API网关分组详情页面找到这个分组对应的API网关提供的公网二级域名。

2. 登录云解析DNS控制台, 在左侧栏单击域名解析,找到要解析的域名,单击域名上的链接进入域名的管理页面。

3. 增加一条需要绑定到API网关的域名的子记录,记录类型选择CNAME ,主机记录填写域名的前缀,记录值填写刚才第一步获取到的公网二级域名,单击确定就完成了。

2.1.2 内网域名解析

  1. 在API网关分组详情页面找到这个分组对应的API网关提供的内网VPC域名。

  2. 登录 PrivateZone控制台,单击页面中的添加Zone,添加PrivateZone 对话框中,输入Zone名称。

说明

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

添加zone

3. 单击Zone名称,可以进入解析记录控制台,为该私有域名添加CNAME解析记录。记录类型选择CNAME ,主机记录填写域名前缀,记录值填写步骤1 获取到的内网VPC域名,单击确定。如图:

PrivateZone解析

4. 前往 PriviteZone 页面。找到刚添加的Zone,单击其操作列下的 关联VPC。在 关联VPC 对话框中,从对应 地域专有网络列表 中选择并添加需要关联的VPC。单击确认,完成关联。

关联VPC

说明

Zone关联VPC后,在被关联VPC内的ECS上,您的Zone(私有域名)将按照PrivateZone解析记录被解析,其公网解析记录则会被覆盖。注意:VPC环境外,该Zone的公网解析记录不受影响。通过为Zone添加PrivateZone解析记录,可以防止记录为空的Zone将需要使用的公网解析覆盖掉,造成异常。更多详情可参考开通PrivateZone文档。

2.2 绑定域名的流程

1. 进入API网关控制台,单击左边菜单的分组管理,进入分组列表页面,然后选择要绑定域名的分组,进入分组详情页面,在页面右下方看到绑定域名的按钮,单击按钮。

2. 进入域名绑定页面,填写刚才做完解析的域名,单击确定。

  • 域名:填写要绑定的域名。

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

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

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

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

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

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

说明

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

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

2.3 域名绑定常见问题

域名绑定失败,会有以下几种情况(附处理办法):

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

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

2.4 调用验证

绑定成功后,我们就可以随意使用绑定的域名来访问这个分组下的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内进行测试。

3.泛域名绑定

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绑定到对应的分组上。

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

重要

仅VPC实例支持泛域名能力。

3.1 绑定泛域名的流程

泛域名的绑定和本文第二章描述的单域名版绑定的流程是大体一致的:

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

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

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

4. 设置分组默认域名

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

在分组详情页面的配置该分组的默认域名:

重要

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