Help us learn about your current experience with the documentation. Take the survey.

Pages 域名 API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed

用于在 GitLab Pages 中连接自定义域名和 TLS 证书的端点。

必须启用 GitLab Pages 功能才能使用这些端点。了解更多关于管理和使用该功能的信息。

列出所有 Pages 域名

前提条件：

您必须具有实例的管理员访问权限。

获取所有 Pages 域名的列表。

GET /pages/domains

如果成功，返回 200 和以下响应属性：

属性	类型	描述
`domain`	string	GitLab Pages 站点的自定义域名。
`url`	string	Pages 站点的完整 URL，包括协议。
`project_id`	integer	与此 Pages 域名关联的 GitLab 项目的 ID。
`verified`	boolean	指示域名是否已验证。
`verification_code`	string	用于验证域名所有权的唯一记录。
`enabled_until`	date	域名启用的截止日期。随着域名重新验证，此日期会定期更新。
`auto_ssl_enabled`	boolean	指示是否为此域名启用了使用 Let’s Encrypt 自动生成 SSL 证书。
`certificate_expiration`	object	SSL 证书到期信息。
`certificate_expiration.expired`	boolean	指示 SSL 证书是否已过期。
`certificate_expiration.expiration`	date	SSL 证书的到期日期和时间。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/pages/domains"

示例响应：

[
  {
    "domain": "ssl.domain.example",
    "url": "https://ssl.domain.example",
    "project_id": 1337,
    "verified": true,
    "verification_code": "1234567890abcdef",
    "enabled_until": "2020-04-12T14:32:00.000Z",
    "auto_ssl_enabled": false,
    "certificate": {
      "expired": false,
      "expiration": "2020-04-12T14:32:00.000Z"
    }
  }
]

列出 Pages 域名

获取项目 Pages 域名的列表。用户必须具有查看 Pages 域名的权限。

GET /projects/:id/pages/domains

支持的属性：

属性	类型	必需	描述
`id`	integer/string	yes	项目的 ID 或 URL 编码的项目路径

如果成功，返回 200 和以下响应属性：

属性	类型	描述
`domain`	string	GitLab Pages 站点的自定义域名。
`url`	string	Pages 站点的完整 URL，包括协议。
`verified`	boolean	指示域名是否已验证。
`verification_code`	string	用于验证域名所有权的唯一记录。
`enabled_until`	date	域名启用的截止日期。随着域名重新验证，此日期会定期更新。
`auto_ssl_enabled`	boolean	指示是否为此域名启用了使用 Let’s Encrypt 自动生成 SSL 证书。
`certificate`	object	SSL 证书信息。
`certificate.subject`	string	SSL 证书的主题，通常包含关于域名的信息。
`certificate.expired`	date	指示 SSL 证书是否已过期（true）或仍然有效（false）。
`certificate.certificate`	string	PEM 格式的完整 SSL 证书。
`certificate.certificate_text`	date	SSL 证书的人类可读文本表示，包括颁发者、有效期、主题和其他证书信息。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

示例响应：

[
  {
    "domain": "www.domain.example",
    "url": "http://www.domain.example",
    "verified": true,
    "verification_code": "1234567890abcdef",
    "enabled_until": "2020-04-12T14:32:00.000Z",
    "auto_ssl_enabled": false,
  },
  {
    "domain": "ssl.domain.example",
    "url": "https://ssl.domain.example",
    "verified": true,
    "verification_code": "1234567890abcdef",
    "enabled_until": "2020-04-12T14:32:00.000Z",
    "auto_ssl_enabled": false,
    "certificate": {
      "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
      "expired": false,
      "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
      "certificate_text": "Certificate:\n … \n"
    }
  }
]

单个 Pages 域名

获取单个项目 Pages 域名。用户必须具有查看 Pages 域名的权限。

GET /projects/:id/pages/domains/:domain

支持的属性：

属性	类型	必需	描述
`id`	integer/string	yes	项目的 ID 或 URL 编码的项目路径
`domain`	string	yes	用户指定的自定义域名

如果成功，返回 200 和以下响应属性：

属性	类型	描述
`domain`	string	GitLab Pages 站点的自定义域名。
`url`	string	Pages 站点的完整 URL，包括协议。
`verified`	boolean	指示域名是否已验证。
`verification_code`	string	用于验证域名所有权的唯一记录。
`enabled_until`	date	域名启用的截止日期。随着域名重新验证，此日期会定期更新。
`auto_ssl_enabled`	boolean	指示是否为此域名启用了使用 Let’s Encrypt 自动生成 SSL 证书。
`certificate`	object	SSL 证书信息。
`certificate.subject`	string	SSL 证书的主题，通常包含关于域名的信息。
`certificate.expired`	date	指示 SSL 证书是否已过期（true）或仍然有效（false）。
`certificate.certificate`	string	PEM 格式的完整 SSL 证书。
`certificate.certificate_text`	date	SSL 证书的人类可读文本表示，包括颁发者、有效期、主题和其他证书信息。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "verified": true,
  "verification_code": "1234567890abcdef",
  "enabled_until": "2020-04-12T14:32:00.000Z",
  "auto_ssl_enabled": false,
  "certificate": {
    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
    "expired": false,
    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
    "certificate_text": "Certificate:\n … \n"
  }
}

创建新的 Pages 域名

创建新的 Pages 域名。用户必须具有创建新 Pages 域名的权限。

POST /projects/:id/pages/domains

支持的属性：

属性	类型	必需	描述
`id`	integer/string	yes	项目的 ID 或 URL 编码的项目路径
`domain`	string	yes	用户指定的自定义域名
`auto_ssl_enabled`	boolean	no	启用由 Let’s Encrypt 为自定义域名颁发的 SSL 证书的自动生成。
`certificate`	file/string	no	PEM 格式的证书，中间证书按从最具体到最不具体的顺序排列。
`key`	file/string	no	PEM 格式的证书密钥。

如果成功，返回 201 和以下响应属性：

属性	类型	描述
`domain`	string	GitLab Pages 站点的自定义域名。
`url`	string	Pages 站点的完整 URL，包括协议。
`verified`	boolean	指示域名是否已验证。
`verification_code`	string	用于验证域名所有权的唯一记录。
`enabled_until`	date	域名启用的截止日期。随着域名重新验证，此日期会定期更新。
`auto_ssl_enabled`	boolean	指示是否为此域名启用了使用 Let’s Encrypt 自动生成 SSL 证书。
`certificate`	object	SSL 证书信息。
`certificate.subject`	string	SSL 证书的主题，通常包含关于域名的信息。
`certificate.expired`	date	指示 SSL 证书是否已过期（true）或仍然有效（false）。
`certificate.certificate`	string	PEM 格式的完整 SSL 证书。
`certificate.certificate_text`	date	SSL 证书的人类可读文本表示，包括颁发者、有效期、主题和其他证书信息。

示例请求：

使用 .pem 文件中的证书创建新的 Pages 域名：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "domain=ssl.domain.example" --form "certificate=@/path/to/cert.pem" \
     --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

使用包含证书的变量创建新的 Pages 域名：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "domain=ssl.domain.example" --form "certificate=$CERT_PEM" \
     --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

创建带有自动证书的新 Pages 域名：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" \
     --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": true,
  "certificate": {
    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
    "expired": false,
    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
    "certificate_text": "Certificate:\n … \n"
  }
}

更新 Pages 域名

更新现有的项目 Pages 域名。用户必须具有更改现有 Pages 域名的权限。

PUT /projects/:id/pages/domains/:domain

支持的属性：

属性	类型	必需	描述
`id`	integer/string	yes	项目的 ID 或 URL 编码的项目路径
`domain`	string	yes	用户指定的自定义域名
`auto_ssl_enabled`	boolean	no	启用由 Let’s Encrypt 为自定义域名颁发的 SSL 证书的自动生成。
`certificate`	file/string	no	PEM 格式的证书，中间证书按从最具体到最不具体的顺序排列。
`key`	file/string	no	PEM 格式的证书密钥。

如果成功，返回 200 和以下响应属性：

属性	类型	描述
`domain`	string	GitLab Pages 站点的自定义域名。
`url`	string	Pages 站点的完整 URL，包括协议。
`verified`	boolean	指示域名是否已验证。
`verification_code`	string	用于验证域名所有权的唯一记录。
`enabled_until`	date	域名启用的截止日期。随着域名重新验证，此日期会定期更新。
`auto_ssl_enabled`	boolean	指示是否为此域名启用了使用 Let’s Encrypt 自动生成 SSL 证书。
`certificate`	object	SSL 证书信息。
`certificate.subject`	string	SSL 证书的主题，通常包含关于域名的信息。
`certificate.expired`	date	指示 SSL 证书是否已过期（true）或仍然有效（false）。
`certificate.certificate`	string	PEM 格式的完整 SSL 证书。
`certificate.certificate_text`	date	SSL 证书的人类可读文本表示，包括颁发者、有效期、主题和其他证书信息。

添加证书

为 Pages 域名添加来自 .pem 文件的证书：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=@/path/to/cert.pem" \
     --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

使用包含证书的变量为 Pages 域名添加证书：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=$CERT_PEM" \
     --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": false,
  "certificate": {
    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
    "expired": false,
    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
    "certificate_text": "Certificate:\n … \n"
  }
}

为 Pages 自定义域名启用 Let’s Encrypt 集成

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": true
}

移除证书

要移除附加到 Pages 域名的 SSL 证书，请运行：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=" \
     --form "key=" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": false
}

验证 Pages 域名

验证现有的项目 Pages 域名。用户必须具有更新 Pages 域名的权限。

PUT /projects/:id/pages/domains/:domain/verify

支持的属性：

属性	类型	必需	描述
`id`	integer/string	yes	项目的 ID 或 URL 编码的项目路径
`domain`	string	yes	要验证的自定义域名

如果成功，返回 200 和以下响应属性：

属性	类型	描述
`domain`	string	GitLab Pages 站点的自定义域名。
`url`	string	Pages 站点的完整 URL，包括协议。
`verified`	boolean	指示域名是否已验证。
`verification_code`	string	用于验证域名所有权的唯一记录。
`enabled_until`	date	域名启用的截止日期。随着域名重新验证，此日期会定期更新。
`auto_ssl_enabled`	boolean	指示是否为此域名启用了使用 Let’s Encrypt 自动生成 SSL 证书。
`certificate`	object	SSL 证书信息。
`certificate.subject`	string	SSL 证书的主题，通常包含关于域名的信息。
`certificate.expired`	date	指示 SSL 证书是否已过期（true）或仍然有效（false）。
`certificate.certificate`	string	PEM 格式的完整 SSL 证书。
`certificate.certificate_text`	date	SSL 证书的人类可读文本表示，包括颁发者、有效期、主题和其他证书信息。

示例请求：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example/verify"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": false,
  "verified": true,
  "verification_code": "1234567890abcdef",
  "enabled_until": "2020-04-12T14:32:00.000Z"
}

删除 Pages 域名

删除现有的项目 Pages 域名。

DELETE /projects/:id/pages/domains/:domain

支持的属性：

属性	类型	必需	描述
`id`	integer/string	yes	项目的 ID 或 URL 编码的项目路径
`domain`	string	yes	用户指定的自定义域名

如果成功，预期会返回一个 204 No Content HTTP 响应，响应体为空。

示例请求：

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"