# Pages domains API

> 原文：[https://docs.gitlab.com/ee/api/pages_domains.html](https://docs.gitlab.com/ee/api/pages_domains.html)

*   [List all pages domains](#list-all-pages-domains)
*   [List pages domains](#list-pages-domains)
*   [Single pages domain](#single-pages-domain)
*   [Create new pages domain](#create-new-pages-domain)
*   [Update pages domain](#update-pages-domain)
    *   [Adding certificate](#adding-certificate)
    *   [Enabling Let’s Encrypt integration for Pages custom domains](#enabling-lets-encrypt-integration-for-pages-custom-domains)
    *   [Removing certificate](#removing-certificate)
*   [Delete pages domain](#delete-pages-domain)

# Pages domains API[](#pages-domains-api "Permalink")

在[GitLab Pages 中](https://about.gitlab.com/stages-devops-lifecycle/pages/)连接自定义域和 TLS 证书的端点.

必须启用 GitLab 页面功能才能使用这些端点. 了解有关[管理](../administration/pages/index.html)和[使用](../user/project/pages/index.html)功能的更多信息.

## List all pages domains[](#list-all-pages-domains "Permalink")

获取所有页面域的列表. 用户必须具有管理员权限.

```
GET /pages/domains 
```

```
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,  "auto_ssl_enabled":  false,  "certificate":  {  "expired":  false,  "expiration":  "2020-04-12T14:32:00.000Z"  }  }  ] 
```

## List pages domains[](#list-pages-domains "Permalink")

Get a list of project pages domains. The user must have permissions to view pages domains.

```
GET /projects/:id/pages/domains 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |

```
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"  },  {  "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"  }  }  ] 
```

## Single pages domain[](#single-pages-domain "Permalink")

获取单个项目页面域. 用户必须具有查看页面域的权限.

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

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `domain` | string | yes | 用户指定的自定义域 |

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

```
{  "domain":  "www.domain.example",  "url":  "http://www.domain.example"  } 
```

```
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",  "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"  }  } 
```

## Create new pages domain[](#create-new-pages-domain "Permalink")

创建一个新的页面域. 用户必须具有创建新页面域的权限.

```
POST /projects/:id/pages/domains 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `domain` | string | yes | 用户指定的自定义域 |
| `auto_ssl_enabled` | boolean | no | 启用[自动生成](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.html)由 Let's Encrypt 为自定义域颁发的 SSL 证书的功能. |
| `certificate` | file/string | no | PEM 格式的证书，其中的中间体按照从最高到最低的顺序排列. |
| `key` | file/string | no | PEM 格式的证书密钥. |

```
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" 
```

```
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" 
```

```
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"  }  } 
```

## Update pages domain[](#update-pages-domain "Permalink")

更新现有的项目页面域. 用户必须具有更改现有页面域的权限.

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

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `domain` | string | yes | 用户指定的自定义域 |
| `auto_ssl_enabled` | boolean | no | 启用[自动生成](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.html)由 Let's Encrypt 为自定义域颁发的 SSL 证书的功能. |
| `certificate` | file/string | no | PEM 格式的证书，其中的中间体按照从最高到最低的顺序排列. |
| `key` | file/string | no | PEM 格式的证书密钥. |

### Adding certificate[](#adding-certificate "Permalink")

```
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" 
```

```
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"  }  } 
```

### Enabling Let’s Encrypt integration for Pages custom domains[](#enabling-lets-encrypt-integration-for-pages-custom-domains "Permalink")

```
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  } 
```

### Removing certificate[](#removing-certificate "Permalink")

要删除附加到 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  } 
```

## Delete pages domain[](#delete-pages-domain "Permalink")

删除现有的项目页面域.

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

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `domain` | string | yes | 用户指定的自定义域 |

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