REST Resource: projects.sites.customDomains

资源：CustomDomain

CustomDomain 是将域名关联到 Firebase Hosting 网站的实体。向您的网站添加 CustomDomain，以允许 Hosting 提供网站内容来响应针对您的域名的请求。

JSON 表示法 
{
  "name": string,
  "annotations": {
    string: string,
    ...
  },
  "createTime": string,
  "updateTime": string,
  "deleteTime": string,
  "expireTime": string,
  "etag": string,
  "hostState": enum (HostState),
  "ownershipState": enum (OwnershipState),
  "requiredDnsUpdates": {
    object (DnsUpdates)
  },
  "issues": [
    {
      object (Status)
    }
  ],
  "certPreference": enum (Type),
  "cert": {
    object (Certificate)
  },
  "redirectTarget": string,
  "reconciling": boolean,
  "labels": {
    string: string,
    ...
  }
}
字段
name

string

仅限输出。CustomDomain 的完全限定名称。
annotations

map (key: string, value: string)

您可以添加注解，以保留有关 CustomDomain 的人类可读和机器可读的元数据。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
createTime

string (Timestamp format)

仅限输出。自定义网域的创建时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

仅限输出。上次更新 CustomDomain 的时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
deleteTime

string (Timestamp format)

仅限输出。CustomDomain 的删除时间；null。删除的自定义网域会保留大约 30 天，之后 Hosting 会将其完全移除。如需恢复已删除的自定义网域，请发出 customDomains.undelete 请求。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
expireTime

string (Timestamp format)

仅限输出。软删除的 CustomDomain 从 Hosting 中完全移除前的最短时间；null。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
etag

string

仅限输出。一个字符串，表示 CustomDomain 的当前状态，可让您在会修改 CustomDomain 的请求中确认其初始状态。使用该标记可确保在发出 customDomains.patch、customDomains.delete 和 customDomains.undelete 请求时保持一致。
hostState

enum (HostState)

仅限输出。此 CustomDomain 所指域名的 HostState。
ownershipState

enum (OwnershipState)

仅限输出。此 CustomDomain 所指域名的 OwnershipState。
requiredDnsUpdates

object (DnsUpdates)

仅限输出。您应该对域名的 DNS 记录进行一组更新，以便 Hosting 代表该域名提供安全内容。
issues[]

object (Status)

仅限输出。Hosting 系统在尝试让 Hosting 能够为您的域名提供安全内容时遇到的一组错误。请解决这些问题，以确保 CustomDomain 正常运行。
certPreference

enum (Type)

一个字段，可让您指定 Hosting 为您的域名创建的 SSL 证书类型。Spark 方案自定义网域只能使用 GROUPED 证书类型，而 Blaze 方案网域可以选择任何选项。
cert

object (Certificate)

仅限输出。Hosting 对此自定义网域的域名所具备的 SSL 证书。对于新的自定义网域，这通常表示 Hosting 想要创建证书，而不是实际证书。如需了解详情，请查看 state 字段。
redirectTarget

string

此 CustomDomain 应将流量定向到的域名。如果指定，Hosting 将使用 HTTP 301 代码响应针对此自定义网域的请求，并改为将流量路由到指定的 redirectTarget。
reconciling

boolean

仅限输出。一个字段，如果为 true，则表示 Hosting 的系统正在参与攻击，以使自定义网域的状态与您的首选状态保持一致。在发出 customDomains.create 请求后首次预配 CustomDomain 时，或在 customDomains.patch 请求后创建新的 SSL 证书以与更新后的 certPreference 匹配时，最常出现这种情况。true
labels

map (key: string, value: string)

用于额外元数据和/或过滤的标签。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

主机状态

您的域名的托管状态。系统会通过检查与您的域名关联的每个 IP 地址来查看其是否在提供 Hosting 内容，从而确定主机状态。

枚举
HOST_STATE_UNSPECIFIED 您的自定义网域的主机状态未指定。如果未指定，消息无效。
HOST_UNHOSTED 您的自定义网域的域名未与任何 IP 地址关联。
HOST_UNREACHABLE 您的自定义网域的域名无法访问。托管服务用于查找域名 IP 地址的 DNS 查询出现错误。如需了解详情，请参阅 CustomDomain 对象的 issues 字段。
HOST_MISMATCH 您的自定义网域的域名具有的 IP 地址最终无法解析为 Hosting。
HOST_CONFLICT 您的自定义网域的域名具有可解析为 Hosting 和其他服务的 IP 地址。为确保结果的一致性，请移除与非托管服务相关的 A 和 AAAA 记录。
HOST_ACTIVE 针对自定义网域的域名的所有请求都由 Hosting 处理。如果自定义网域的 OwnershipState 也是 ACTIVE，则 Hosting 会在域名上提供您的 Hosting 网站的内容。

所有权状态

网域的所有权状态。一个网域最多只能归一个 Firebase Hosting 网站拥有。可以通过以下两种方式确定所有权：

* TXT records: A TXT record on the domain in the form
`hosting-site=[siteId]`.
* CNAME records: A CNAME record that points to a Hosting site's default
domain.

如果您的 CustomDomain 处于 OWNERSHIP_ACTIVE 以外的OwnershipState中超过 30 天，并且至少有 30 天未更新，Hosting 的所有权系统会删除 CustomDomain。如需恢复已删除的 CustomDomain，请发出 customDomains.undelete 请求。

枚举
OWNERSHIP_STATE_UNSPECIFIED 您的自定义网域的所有权状态未指定。这种情况绝不应发生。
OWNERSHIP_MISSING 您的自定义网域的域名没有与 Hosting 相关的所有权记录；没有任何 Firebase 项目有权代表该域名执行操作。
OWNERSHIP_UNREACHABLE 您的自定义网域的域名无法访问。托管服务用于查找域名所有权记录的 DNS 查询导致了错误。如需了解详情，请参阅 CustomDomain 对象的 issues 字段。
OWNERSHIP_MISMATCH 您的自定义网域的域名归其他 Firebase 项目所有。移除有冲突的 TXT 记录，并将其替换为当前 Firebase 项目的项目专用记录。
OWNERSHIP_CONFLICT 您的自定义网域的域名存在相互冲突的 TXT 记录，这些记录指示当前 Firebase 项目和其他项目的所有权。移除其他项目的所有权记录，以授予当前项目的所有权。
OWNERSHIP_PENDING 您的自定义网域的 DNS 记录已正确配置。Hosting 会在 24 小时内将您的域名所有权转移给此 CustomDomain。
OWNERSHIP_ACTIVE 您的自定义网域的域名有 TXT 记录，这些记录向其项目授予了代表其执行操作的权限。

DNS 更新

为允许 Hosting 提供安全内容以响应针对您的域名的请求，您应进行的一组 DNS 记录更新。这些更新会显示在 Hosting 上次查询您的域名 DNS 记录时的当前状态，以及 Hosting 需要查看的一组所需记录，以便自定义网域完全生效。

JSON 表示法 
{
  "discovered": [
    {
      object (DnsRecordSet)
    }
  ],
  "desired": [
    {
      object (DnsRecordSet)
    }
  ],
  "checkTime": string
}
字段
discovered[]

object (DnsRecordSet)

Hosting 在检查网域时发现的一组 DNS 记录。
desired[]

object (DnsRecordSet)

Hosting 需要这组 DNS 记录才能在网域上提供安全内容。
checkTime

string (Timestamp format)

Hosting 上次检查自定义网域的 DNS 记录的时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

DnsRecordSet

与 Firebase Hosting 中自定义网域的设置和维护相关的一组 DNS 记录。

JSON 表示法 
{
  "domainName": string,
  "checkError": {
    object (Status)
  },
  "records": [
    {
      object (DnsRecord)
    }
  ]
}
字段
domainName

string

仅限输出。记录集相关的域名。
checkError

object (Status)

仅限输出。查询您域名的 DNS 记录时托管服务遇到错误。注意：Hosting 会忽略 NXDOMAIN 错误，因为这些错误通常只表示尚未设置域名。
records[]

object (DnsRecord)

仅限输出。域名上的记录。

DNSRecord

DNS 记录是资源记录，用于定义系统和服务在处理域名请求时应采取的行为。例如，如果您将 A 记录添加到域名的 DNS 记录中，即表示您告知其他系统（例如用户的网络浏览器）联系这些 IPv4 地址，以检索与您的域名相关的资源（例如 Hosting 网站文件）。

JSON 表示法 
{
  "domainName": string,
  "type": enum (Type),
  "rdata": string,
  "requiredAction": enum (Action)
}
字段
domainName

string

仅限输出。记录与域名相关的域名，例如foo.bar.com.。
type

enum (Type)

仅限输出。记录的类型，用于确定记录包含哪些数据。
rdata

string

仅限输出。记录的数据。该值的含义取决于记录类型：- A 和 AAAA：域名的 IP 地址。- CNAME：要检查记录的其他域。- TXT：与域名关联的任意文本字符串。Hosting 使用 TXT 记录来确定哪些 Firebase 项目有权代表域名执行操作。- CAA：记录的标志、标记和值，例如0 issue "pki.goog"。
requiredAction

enum (Action)

仅限输出。指示此记录的所需操作的枚举。

类型

DNS 记录的类型，包括 A、TXT、AAAA 和 CAA。

枚举
TYPE_UNSPECIFIED 未指定记录的类型。如果未指定，消息无效。
A A 记录，如 RFC 1035 中所定义。A 记录用于确定域名将流量定向到哪些 IPv4 地址。
CNAME CNAME 记录（如 RFC 1035 中所定义）。CNAME（即规范名称）记录可将域名映射到其他规范域名。如果存在 CNAME 记录，则它应该是域名上的唯一记录。
TXT TXT 记录（如 RFC 1035 中所定义）。TXT 记录用于保存域名中的任意文本数据。Hosting 使用 TXT 记录来确定哪个 Firebase 项目有权对域名执行操作。
AAAA AAAA 记录（如 RFC 3596 中所述）AAAA 记录确定域名将流量定向到哪个 IPv6 地址。
CAA

CAA 记录，如 RFC 6844 中所定义。CAA（证书授权机构授权）记录可确定哪些证书授权机构（SSL 证书创建组织）有权为域名创建证书。Firebase Hosting 使用 pki.goog 作为其主 CA。

CAA 记录级联。foo.com 上的 CAA 记录也适用于 bar.foo.com，除非 bar.foo.com 拥有自己的一组 CAA 记录。

CAA 记录是可选的。如果域名及其父级没有 CAA 记录，则所有 CA 都有权代表该域名创建证书。一般来说，Hosting 仅在需要修改 CAA 记录才能取消屏蔽创建 SSL 证书时要求您修改 CAA 记录。

操作

“操作”是指您应该对此 DNS 记录执行的操作类型，以配置您的网域以与 Firebase Hosting 搭配使用。

枚举
NONE 您无需执行任何操作。
ADD 将此记录添加到您的 DNS 记录中。
REMOVE 从您的 DNS 记录中移除此记录。

类型

证书的类型。确定 Hosting 系统如何处理证书的创建和维护。

枚举
TYPE_UNSPECIFIED 未指定证书类型。如果未指定，消息无效。
TEMPORARY 一种短期有效的证书类型，用于暂时覆盖域名，而 Hosting 会创建更永久的证书。
GROUPED Spark 方案自定义网域的标准证书。
PROJECT_GROUPED 仅限 Blaze 方案。一个证书，可涵盖同一 Firebase 项目中具有自定义网域（1 到 100 个）的域名。
DEDICATED 仅限 Blaze 方案。涵盖单个域名的证书。

证书

用于为针对您的域名的请求提供端到端加密的 SSL 证书。Certificate 可以是实际的 SSL 证书，对于新创建的自定义网域而言，Hosting 的用途可以是 Hosting 创建一个证书。

JSON 表示法 
{
  "type": enum (Type),
  "state": enum (CertState),
  "verification": {
    object (CertVerification)
  },
  "issues": [
    {
      object (Status)
    }
  ],
  "createTime": string,
  "expireTime": string
}
字段
type

enum (Type)

仅限输出。证书的类型。
state

enum (CertState)

仅限输出。证书的状态。只有 CERT_ACTIVE 和 CERT_EXPIRING_SOON 状态可为域名提供 SSL 覆盖范围。如果状态为 PROPAGATING，并且 Hosting 之前具有域名的有效证书，则先前的有效证书将为域名提供 SSL 覆盖范围，直到当前证书传播。
verification

object (CertVerification)

仅限输出。您可以添加到 DNS 记录或现有的非 Hosting 托管服务提供商的一组 ACME 验证，以允许 Hosting 先为您的域名创建 SSL 证书，然后再将流量引向托管。您可以在从旧提供商到 Hosting 的零停机过渡期间使用这些挑战。
issues[]

object (Status)

仅限输出。Hosting 在尝试为您的域名创建证书时遇到的一组错误。请解决这些问题，以确保 Hosting 能与网站访问者安全通信。
createTime

string (Timestamp format)

仅限输出。证书的创建时间。对于 TEMPORARY 证书，这是 Hosting 首次为您的域名生成验证的时间。对于所有其他证书类型，该时间是实际证书的创建时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
expireTime

string (Timestamp format)

仅限输出。证书的到期时间。此后，无法再使用该证书在 Hosting 和网站访问者之间提供安全通信。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

CertState

Hosting 对您的域名的 SSL 证书的状态。这可以表示实际证书的状态，对于新的自定义网域，可以表示 Hosting 创建证书的尝试。

枚举
CERT_STATE_UNSPECIFIED 证书的状态未指定。如果未指定，消息无效。
CERT_PREPARING 每个证书的初始状态表示在向证书授权机构发出请求之前，Hosting 创建证书的意图。
CERT_VALIDATING Hosting 正在验证域名的 DNS 记录是否处于允许代表其创建证书的状态。
CERT_PROPAGATING 该证书是最近创建的，需要一些时间在 Hosting 的 CDN 中传播。
CERT_ACTIVE 该证书处于有效状态，为其所代表的域名提供安全连接。
CERT_EXPIRING_SOON 此证书即将过期，其中的所有域名都将获得新证书。
CERT_EXPIRED 证书已过期。Hosting 无法再在您的域名中提供安全内容。

认证

一组 ACME 验证，您可以使用这些验证来允许 Hosting 为您的域名创建 SSL 证书，然后再将流量定向到 Hosting 服务器。使用 DNS 或 HTTP 质询；则不必同时提供两者。

JSON 表示法 
{
  "dns": {
    object (DnsUpdates)
  },
  "http": {
    object (HttpUpdate)
  }
}
字段
dns

object (DnsUpdates)

仅限输出。添加到 DNS 记录的 TXT 记录，用于确认您打算让 Hosting 为您的域名创建 SSL 证书。
http

object (HttpUpdate)

仅限输出。要添加到现有的非 Hosting 托管服务的文件，用于确认您打算让 Hosting 为您的域名创建 SSL 证书。

HttpUpdate 类中的方法

可添加到现有的非 Hosting 托管服务的文件，用于确认您打算允许 Hosting 的证书授权机构为您的网域创建 SSL 证书。

JSON 表示法 
{
  "path": string,
  "desired": string,
  "discovered": string,
  "lastCheckTime": string,
  "checkError": {
    object (Status)
  }
}
字段
path

string

仅限输出。文件的路径。
desired

string

仅限输出。要在路径中提供的文本字符串。
discovered

string

仅限输出。Hosting 在其上次检查期间是否能够在指定路径上找到所需的文件内容。
lastCheckTime

string (Timestamp format)

仅限输出。Hosting 系统上次检查文件内容的时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
checkError

object (Status)

仅限输出。上次内容检查时出错。如果为 null，则表示检查已成功完成。

方法

create

 创建 CustomDomain。

delete

 删除指定的 CustomDomain。

get

 获取指定的 CustomDomain。

list

 列出与指定的父级 Hosting 网站关联的每个 CustomDomain。

patch

 更新指定的 CustomDomain。

undelete

 恢复已软删除的指定 CustomDomain。