REST Resource: projects.sites.customDomains

資源：CustomDomain

CustomDomain 是將網域名稱連結至 Firebase 託管網站的實體。在網站中新增 CustomDomain，允許「託管」回應你網域名稱的要求，提供網站內容。

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 世界標準時間「Zulu」的時間戳記格式，解析度不超過奈秒，最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

僅供輸出。上次更新 CustomDomain 的時間。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度不超過奈秒，最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
deleteTime

string (Timestamp format)

僅供輸出。刪除「CustomDomain」的時間。如果自訂網域尚未刪除，則為空值。遭到刪除的自訂網域會保留約 30 天，之後由代管服務完全移除。如要還原已刪除的自訂網域，請提出 customDomains.undelete 要求。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度不超過奈秒，最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
expireTime

string (Timestamp format)

僅供輸出。虛刪除的 CustomDomain 從代管服務完全移除之前的最短時間。如果自訂網域尚未刪除，則為空值。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度不超過奈秒，最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
etag

string

僅供輸出。代表 CustomDomain 目前狀態的字串，讓您在修改之要求中確認其初始狀態。提出 customDomains.patch、customDomains.delete 和 customDomains.undelete 要求時，請使用標記以確保一致性。
hostState

enum (HostState)

僅供輸出。這個 CustomDomain 參照的網域名稱的 HostState。
ownershipState

enum (OwnershipState)

僅供輸出。這個 CustomDomain 參照的網域名稱的 OwnershipState。
requiredDnsUpdates

object (DnsUpdates)

僅供輸出。您應更新網域名稱的 DNS 記錄的一組更新，以便「託管」代為提供安全內容。
issues[]

object (Status)

僅供輸出。託管系統在嘗試建立「託管」為網域名稱提供安全內容時遇到的一組錯誤。請解決這些問題，確保 CustomDomain 能正常運作。
certPreference

enum (Type)

這個欄位可讓你指定要為網域名稱「託管」建立的 SSL 憑證類型。Spark 方案自訂網域只能使用「GROUPED」憑證類型，Blaze 方案網域則可選取任何選項。
cert

object (Certificate)

僅供輸出。這個自訂網域的網域名稱由 SSL 憑證代管。如果是新的自訂網域，這通常代表「主機」建立憑證的意圖，而非實際憑證。詳情請參閱 state 欄位。
redirectTarget

string

這個 CustomDomain 應將流量導向的網域名稱。如有指定，「託管」會以 HTTP 301 代碼回應針對這個自訂網域提出的要求，並將流量轉至指定的 redirectTarget。
reconciling

boolean

僅供輸出。如果此欄位為 true，表示「託管」的系統正在設法讓自訂網域的狀態符合您偏好的狀態。最常在發生 customDomains.create 要求後佈建 CustomDomain 時，或是建立新的 SSL 憑證 (用於符合 customDomains.patch 要求後更新過的 certPreference) 時，最常出現的 true。
labels

map (key: string, value: string)

用於額外中繼資料和/或篩選的標籤。

包含 "key": value 組合清單的物件。範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

主機狀態

網域名稱的主機狀態。主機狀態取決於每個與網域名稱相關聯的 IP 位址，確認主機是否提供代管內容。

列舉
HOST_STATE_UNSPECIFIED 您未指定自訂網域的主機狀態。如未指定，則訊息無效。
HOST_UNHOSTED 自訂網域的網域名稱未與任何 IP 位址建立關聯。
HOST_UNREACHABLE 無法連線至自訂網域的網域名稱。代管服務透過 DNS 查詢找出網域名稱的 IP 位址，藉此找出錯誤。詳情請參閱 CustomDomain 物件的 issues 欄位。
HOST_MISMATCH 自訂網域網域名稱的 IP 位址最終不會解析為「託管」。
HOST_CONFLICT 自訂網域網域名稱的 IP 位址可解析為「託管」和其他服務。為確保結果一致，請移除與非代管服務相關的 A 和 AAAA 記錄。
HOST_ACTIVE 所有對您自訂網域名稱發出的要求皆由「託管」處理。如果自訂網域的 OwnershipState 同時也是「ACTIVE」，「代管」會在網域名稱中提供「代管」網站的內容。

擁有權狀態

網域的擁有權狀態。一個網域最多只能擁有一個 Firebase 託管網站。擁有者可透過兩種方式判定擁有權：

* 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 天未更新，「代管」的擁有權系統會刪除 CustomDomain。如要還原已刪除的 CustomDomain，請提出 customDomains.undelete 要求。

列舉
OWNERSHIP_STATE_UNSPECIFIED 您未指定自訂網域的擁有權狀態。這種情況絕不應該發生。
OWNERSHIP_MISSING 自訂網域的網域名稱沒有「託管」相關擁有權記錄。沒有任何 Firebase 專案有權代表網域名稱執行動作。
OWNERSHIP_UNREACHABLE 無法連線至自訂網域的網域名稱。代管服務透過 DNS 查詢來找出網域名稱的擁有權記錄，但發生錯誤。詳情請參閱 CustomDomain 物件的 issues 欄位。
OWNERSHIP_MISMATCH 自訂網域的網域名稱屬於其他 Firebase 專案。移除相衝突的 TXT 記錄，並替換為目前 Firebase 專案中的專案專屬記錄。
OWNERSHIP_CONFLICT 自訂網域的網域名稱有衝突的 TXT 記錄，可指出目前 Firebase 專案和其他專案的擁有權。移除其他專案的擁有權記錄，授予目前的專案擁有權。
OWNERSHIP_PENDING 自訂網域的 DNS 記錄設定正確無誤。「託管」會在 24 小時內將網域的擁有權轉移至這部 CustomDomain。
OWNERSHIP_ACTIVE 自訂網域的網域名稱中有 TXT 項記錄可授予專案代表網域執行動作的權限。

DNS 更新

你必須更新一組 DNS 記錄，「託管」伺服器才能回應你網域名稱的要求，提供安全內容。這些更新會顯示「託管」上次查詢網域名稱的 DNS 記錄目前狀態，以及「代管」作業在自訂網域全面啟用前所需的記錄集。

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

object (DnsRecordSet)

在檢查網域時發現的 DNS 記錄集。
desired[]

object (DnsRecordSet)

「託管」的 DNS 記錄集必須在網域上提供安全內容。
checkTime

string (Timestamp format)

「代管服務」上次檢查了自訂網域的 DNS 記錄。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度不超過奈秒，最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

DnsRecordSet

與在 Firebase 託管中設定及維護自訂網域相關的 DNS 記錄。

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

string

僅供輸出。屬於記錄集的網域名稱。
checkError

object (Status)

僅供輸出。查詢網域名稱的 DNS 記錄時，「託管」服務發生錯誤。注意：「代管服務」會忽略 NXDOMAIN 錯誤，因為這類錯誤通常只是表示尚未設定網域名稱。
records[]

object (DnsRecord)

僅供輸出。網域中的記錄。

DNS 記錄

DNS 記錄是一種資源記錄，可定義系統和服務在處理網域名稱要求時應採取的行為。舉例來說，如果您在網域名稱的 DNS 記錄中加入 A 記錄，就能通知其他系統 (例如使用者的網路瀏覽器) 與這些 IPv4 位址聯絡，以便擷取與您網域名稱相關的資源 (例如代管網站檔案)。

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：與網域名稱相關聯的任意文字字串。「託管」會根據 TXT 記錄，判斷哪些 Firebase 專案有權代表網域名稱執行動作。- CAA：記錄的旗標、標記和值，例如0 issue "pki.goog"。
requiredAction

enum (Action)

僅供輸出。列舉，表示這項記錄的必要動作。

類型

DNS 記錄的類型，包括 A、TXT、AAAA 和 CAA。

列舉
TYPE_UNSPECIFIED 未指定記錄的類型。如未指定，則訊息無效。
A RFC 1035 中定義的 A 記錄。A 記錄會決定網域名稱將流量導向哪些 IPv4 位址。
CNAME RFC 1035 中定義的 CNAME 記錄。CNAME 或正規名稱記錄會將網域名稱對應到不同的正規網域名稱。如有 CNAME 記錄，則網域名稱上應是唯一的記錄。
TXT RFC 1035 中定義的 TXT 記錄。TXT 記錄會保留網域名稱上的任意文字資料。「託管」會使用 TXT 記錄，決定哪些 Firebase 專案有權對網域名稱執行動作。
AAAA 根據 RFC 3596 AAAA 記錄中的定義，AAAA 記錄會決定將流量導向哪些 IPv6 地址。
CAA

CAA 記錄，如 RFC 6844 中定義。CAA (簡稱「憑證授權單位授權」) 的記錄會決定哪些憑證授權單位 (SSL 憑證採礦機構) 有權建立網域名稱的憑證。Firebase 託管使用 pki.goog 做為主要 CA。

CAA 記錄序列。foo.com 上的 CAA 記錄也會套用至 bar.foo.com，除非 bar.foo.com 擁有自己的一組 CAA 記錄。

CAA 記錄為選用項目。如果網域名稱及其父項沒有 CAA 記錄，則所有 CA 均有權代表其建立憑證。一般而言，「託管」只會在需要修改 CAA 記錄時要求您修改 CAA 記錄，才能解除封鎖 SSL 憑證建立作業。

動作

您必須對這項 DNS 記錄執行動作，設定網域，才能在 Firebase 託管中使用。

列舉
NONE 不需要採取任何行動。
ADD 將這筆記錄新增至 DNS 記錄。
REMOVE 從 DNS 記錄中移除這筆記錄。

類型

憑證類型。決定託管系統處理建立及維護憑證的方式。

列舉
TYPE_UNSPECIFIED 未指定憑證類型。如未指定，則訊息無效。
TEMPORARY 這種短期憑證類型會暫時涵蓋網域名稱，「託管」則會建立更永久的憑證。
GROUPED Spark 方案自訂網域的標準憑證。
PROJECT_GROUPED 僅限 Blaze 方案。憑證包含 1 到 100 個網域名稱，且名稱來自同一項 Firebase 專案內的自訂網域。
DEDICATED 僅限 Blaze 方案。包含單一網域名稱的憑證。

憑證

安全資料傳輸層 (SSL) 憑證，可用來為網域名稱發出的要求提供端對端加密機制。Certificate 可以是實際的安全資料傳輸層 (SSL) 憑證，也可以是新建立的自訂網域的「託管」意圖建立憑證。

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，且「託管」之前已有網域名稱的有效憑證，則先前使用的憑證會提供網域名稱的 SSL 涵蓋範圍，直到目前的憑證傳播為止。
verification

object (CertVerification)

僅供輸出。你可以將一組 ACME 驗證問題新增至 DNS 記錄，或用於允許「託管」建立網域名稱的 SSL 憑證，再將流量指向代管服務。您可以將舊供應商轉移至「託管」的零停機時間，藉此克服各種挑戰。
issues[]

object (Status)

僅供輸出。「託管」嘗試建立網域名稱的憑證時，發生了一組錯誤。請解決這些問題，確保「託管」能夠與您的訪客安全地進行通訊。
createTime

string (Timestamp format)

僅供輸出。憑證的建立時間。如果是 TEMPORARY 憑證，這是指「託管」首次為網域名稱產生的挑戰。至於其他所有憑證類型，則這指的是實際建立憑證的時間。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度不超過奈秒，最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
expireTime

string (Timestamp format)

僅供輸出。憑證的到期時間。之後，該憑證將無法再用來為「代管」作業和網站訪客進行安全通訊。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度不超過奈秒，最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

憑證

網域名稱託管的 SSL 憑證狀態。這可以表示實際憑證的狀態，如果是新的自訂網域，則可代表「託管」嘗試建立憑證。

列舉
CERT_STATE_UNSPECIFIED 未指定憑證的狀態。如未指定，則訊息無效。
CERT_PREPARING 每個憑證的初始狀態，代表「主機」在建立憑證的要求之前，會建立憑證。
CERT_VALIDATING 「託管」會驗證網域名稱的 DNS 記錄是否處於允許代表網域建立憑證的狀態。
CERT_PROPAGATING 憑證最近才建立，需要一段時間才能在託管的 CDN 中全面生效。
CERT_ACTIVE 憑證處於有效狀態，能為其代表的網域名稱提供安全連線。
CERT_EXPIRING_SOON 憑證即將到期，上面的所有網域名稱都會獲得新憑證。
CERT_EXPIRED 憑證已到期。「代管」無法再透過您的網域提供安全內容。

認證

你可以透過一組 ACME 驗證，允許「託管」為網域名稱建立 SSL 憑證，再將流量導向「託管」伺服器。使用 DNS 或 HTTP 驗證；不需要同時提供這兩種資訊

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

object (DnsUpdates)

僅供輸出。要新增至 DNS 記錄的 TXT 記錄，用於確認意圖允許託管為網域名稱建立 SSL 憑證。
http

object (HttpUpdate)

僅供輸出。將這個檔案加入現有的非代管代管服務中，確認你的意圖允許託管為網域名稱建立 SSL 憑證。

HttpUpdate

在現有的非代管代管服務中新增檔案，證明你的意圖允許「託管」的憑證授權單位為網域建立 SSL 憑證。

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

string

僅供輸出。檔案路徑。
desired

string

僅供輸出。要在路徑上執行的文字字串。
discovered

string

僅供輸出。「託管」在上次檢查時是否能在指定路徑中找到必要檔案內容。
lastCheckTime

string (Timestamp format)

僅供輸出。「主機」系統上次檢查檔案內容的時間。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度不超過奈秒，最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
checkError

object (Status)

僅供輸出。上次檢查內容時發生錯誤。如果是空值，表示檢查已順利完成。

方法

create

 可建立 CustomDomain。

delete

 刪除指定的 CustomDomain。

get

 取得指定的 CustomDomain。

list

 列出與指定父項託管網站相關聯的每個 CustomDomain。

patch

 更新指定的 CustomDomain。

undelete

 如果指定的 CustomDomain 已虛刪除，則會取消刪除。