PagesドメインAPI

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed

このAPIを使用して、GitLab Pagesドメインを管理します。

これらのエンドポイントを使用するには、GitLab Pages機能を有効にする必要があります。この機能の管理と使用について詳しくはこちらをご覧ください。

すべてのPagesドメインをリストする

インスタンス上のすべてのPagesドメインをリストします。

前提条件:

インスタンスへの管理者アクセス権が必要です。

GET /pages/domains

サポートされている属性は以下のとおりです:

属性	型	必須	説明
`domain`	文字列	いいえ	フィルタリング対象のGitLab Pagesサイトのドメイン。

成功した場合、200と次のレスポンス属性を返します:

属性	型	説明
`domain`	文字列	GitLab Pagesサイトのカスタムドメイン名。
`url`	文字列	プロトコルを含むPagesサイトの完全なURL。
`project_id`	整数	このPagesドメインに関連付けられたGitLabプロジェクトのID。
`verified`	ブール値	ドメインが検証済みかどうかを示します。
`verification_code`	文字列	ドメインの所有権を検証するために使用される一意のレコード。
`enabled_until`	日付	ドメインが有効になる日付。これは、ドメインが再検証されると定期的に更新されます。
`auto_ssl_enabled`	ブール値	Let’s Encryptを使用したSSL証明書の自動生成が、このドメインで有効になっているかどうかを示します。
`certificate_expiration`	オブジェクト	SSL証明書の有効期限に関する情報。
`certificate_expiration.expired`	ブール値	SSL証明書の有効期限が切れているかどうかを示します。
`certificate_expiration.expiration`	日付	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`	整数または文字列	はい	プロジェクトのIDまたはURLエンコードされたパス

成功した場合、200と次のレスポンス属性を返します:

属性	型	説明
`domain`	文字列	GitLab Pagesサイトのカスタムドメイン名。
`url`	文字列	プロトコルを含むPagesサイトの完全なURL。
`verified`	ブール値	ドメインが検証済みかどうかを示します。
`verification_code`	文字列	ドメインの所有権を検証するために使用される一意のレコード。
`enabled_until`	日付	ドメインが有効になる日付。これは、ドメインが再検証されると定期的に更新されます。
`auto_ssl_enabled`	ブール値	Let’s Encryptを使用したSSL証明書の自動生成が、このドメインで有効になっているかどうかを示します。
`certificate`	オブジェクト	SSL証明書に関する情報。
`certificate.subject`	文字列	ドメインに関する情報を含む、SSL証明書のサブジェクト。
`certificate.expired`	日付	SSL証明書の有効期限が切れている（true）か、まだ有効である（false）かを示します。
`certificate.certificate`	文字列	PEM形式の完全なSSL証明書。
`certificate.certificate_text`	日付	発行者、有効期間、サブジェクト、その他の証明書情報などの詳細を含む、SSL証明書の人間が読めるテキスト表現。

リクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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`	整数または文字列	はい	プロジェクトのIDまたはURLエンコードされたパス
`domain`	文字列	はい	ユーザーが指定したカスタムドメイン

成功した場合、200と次のレスポンス属性を返します:

属性	型	説明
`domain`	文字列	GitLab Pagesサイトのカスタムドメイン名。
`url`	文字列	プロトコルを含むPagesサイトの完全なURL。
`verified`	ブール値	ドメインが検証済みかどうかを示します。
`verification_code`	文字列	ドメインの所有権を検証するために使用される一意のレコード。
`enabled_until`	日付	ドメインが有効になる日付。これは、ドメインが再検証されると定期的に更新されます。
`auto_ssl_enabled`	ブール値	Let’s Encryptを使用したSSL証明書の自動生成が、このドメインで有効になっているかどうかを示します。
`certificate`	オブジェクト	SSL証明書に関する情報。
`certificate.subject`	文字列	ドメインに関する情報を含む、SSL証明書のサブジェクト。
`certificate.expired`	日付	SSL証明書の有効期限が切れている（true）か、まだ有効である（false）かを示します。
`certificate.certificate`	文字列	PEM形式の完全なSSL証明書。
`certificate.certificate_text`	日付	発行者、有効期間、サブジェクト、その他の証明書情報などの詳細を含む、SSL証明書の人間が読めるテキスト表現。

リクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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`	整数または文字列	はい	プロジェクトのIDまたはURLエンコードされたパス
`domain`	文字列	はい	ユーザーが指定したカスタムドメイン
`auto_ssl_enabled`	ブール値	いいえ	カスタムドメインに対して、Let’s Encryptによって発行されたSSL証明書の自動生成を有効にします。
`certificate`	ファイル/文字列	いいえ	最も具体的なものから最も具体的でないものの順に中間証明書が続くPEM形式の証明書。
`key`	ファイル/文字列	いいえ	PEM形式の証明書キー。

成功した場合、201と次のレスポンス属性を返します:

属性	型	説明
`domain`	文字列	GitLab Pagesサイトのカスタムドメイン名。
`url`	文字列	プロトコルを含むPagesサイトの完全なURL。
`verified`	ブール値	ドメインが検証済みかどうかを示します。
`verification_code`	文字列	ドメインの所有権を検証するために使用される一意のレコード。
`enabled_until`	日付	ドメインが有効になる日付。これは、ドメインが再検証されると定期的に更新されます。
`auto_ssl_enabled`	ブール値	Let’s Encryptを使用したSSL証明書の自動生成が、このドメインで有効になっているかどうかを示します。
`certificate`	オブジェクト	SSL証明書に関する情報。
`certificate.subject`	文字列	ドメインに関する情報を含む、SSL証明書のサブジェクト。
`certificate.expired`	日付	SSL証明書の有効期限が切れている（true）か、まだ有効である（false）かを示します。
`certificate.certificate`	文字列	PEM形式の完全なSSL証明書。
`certificate.certificate_text`	日付	発行者、有効期間、サブジェクト、その他の証明書情報などの詳細を含む、SSL証明書の人間が読めるテキスト表現。

リクエストの例:

.pemファイルから証明書を使用して新しいPagesドメインを作成する:

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

証明書を含む変数を使用して新しいPagesドメインを作成する:

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

自動証明書を使用して新しい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`	整数または文字列	はい	プロジェクトのIDまたはURLエンコードされたパス
`domain`	文字列	はい	ユーザーが指定したカスタムドメイン
`auto_ssl_enabled`	ブール値	いいえ	カスタムドメインに対して、Let’s Encryptによって発行されたSSL証明書の自動生成を有効にします。
`certificate`	ファイル/文字列	いいえ	最も具体的なものから最も具体的でないものの順に中間証明書が続くPEM形式の証明書。
`key`	ファイル/文字列	いいえ	PEM形式の証明書キー。

成功した場合、200と次のレスポンス属性を返します:

属性	型	説明
`domain`	文字列	GitLab Pagesサイトのカスタムドメイン名。
`url`	文字列	プロトコルを含むPagesサイトの完全なURL。
`verified`	ブール値	ドメインが検証済みかどうかを示します。
`verification_code`	文字列	ドメインの所有権を検証するために使用される一意のレコード。
`enabled_until`	日付	ドメインが有効になる日付。これは、ドメインが再検証されると定期的に更新されます。
`auto_ssl_enabled`	ブール値	Let’s Encryptを使用したSSL証明書の自動生成が、このドメインで有効になっているかどうかを示します。
`certificate`	オブジェクト	SSL証明書に関する情報。
`certificate.subject`	文字列	ドメインに関する情報を含む、SSL証明書のサブジェクト。
`certificate.expired`	日付	SSL証明書の有効期限が切れている（true）か、まだ有効である（false）かを示します。
`certificate.certificate`	文字列	PEM形式の完全なSSL証明書。
`certificate.certificate_text`	日付	発行者、有効期間、サブジェクト、その他の証明書情報などの詳細を含む、SSL証明書の人間が読めるテキスト表現。

証明書を追加する

.pemファイルからPagesドメインの証明書を追加する:

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

証明書を含む変数を使用してPagesドメインの証明書を追加する:

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

レスポンス例:

{
  "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>" \
  --url "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" \
  --form "auto_ssl_enabled=true"

レスポンス例:

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

証明書を削除する

Pagesドメインに添付されているSSL証明書を削除するには、以下を実行します:

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

レスポンス例:

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

Pagesドメインを検証する

プロジェクト内の指定されたPagesドメインを検証します。ユーザーはPagesドメインを更新する権限を持っている必要があります。

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

サポートされている属性は以下のとおりです:

属性	型	必須	説明
`id`	整数または文字列	はい	プロジェクトのIDまたはURLエンコードされたパス
`domain`	文字列	はい	検証するカスタムドメイン

成功した場合、200と次のレスポンス属性を返します:

属性	型	説明
`domain`	文字列	GitLab Pagesサイトのカスタムドメイン名。
`url`	文字列	プロトコルを含むPagesサイトの完全なURL。
`verified`	ブール値	ドメインが検証済みかどうかを示します。
`verification_code`	文字列	ドメインの所有権を検証するために使用される一意のレコード。
`enabled_until`	日付	ドメインが有効になる日付。これは、ドメインが再検証されると定期的に更新されます。
`auto_ssl_enabled`	ブール値	Let’s Encryptを使用したSSL証明書の自動生成が、このドメインで有効になっているかどうかを示します。
`certificate`	オブジェクト	SSL証明書に関する情報。
`certificate.subject`	文字列	ドメインに関する情報を含む、SSL証明書のサブジェクト。
`certificate.expired`	日付	SSL証明書の有効期限が切れている（true）か、まだ有効である（false）かを示します。
`certificate.certificate`	文字列	PEM形式の完全なSSL証明書。
`certificate.certificate_text`	日付	発行者、有効期間、サブジェクト、その他の証明書情報などの詳細を含む、SSL証明書の人間が読めるテキスト表現。

リクエスト例:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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`	整数または文字列	はい	プロジェクトのIDまたはURLエンコードされたパス
`domain`	文字列	はい	ユーザーが指定したカスタムドメイン

成功した場合、空のボディを持つ204 No Content HTTPレスポンスが期待されます。

リクエスト例:

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