Package google.digitalassetlinks.v1

索引

聲明

這項 API 服務會提供「聲明」，也就是資產擁有者用來發布資產連結相關資訊的車輛。只要使用這個 API，即可透過簡單又安全的方式擷取陳述式，而不必直接從來源取得陳述式。

這個 API 傳回的所有聲明都代表其他數位資產的數位資產 (例如網站或 Android 應用程式)。每個陳述式都包含來源資產、目標資產和一或多個關係。

「關聯」指的是兩項資產之間 (依來源資產聲明擁有權) 之間的關係。這類關係的例子就是權限或權限的委派。

清單

rpc List(ListRequest) returns (ListResponse)

擷取指定來源中符合指定目標和陳述式字串的所有陳述式清單。

根據「Digital Asset Links 技術設計規格」所述，這個 API 能保證所有含有安全來源資產 (例如 HTTPS 網站或 Android 應用程式) 的陳述式均以安全的方式提交。具體而言，如果網站不安全 (也就是網址開頭為 http://，而非 https://)，則無法做出這項保證。

當 API 用戶端想要瞭解兩項資產相關的所有方式，或列舉特定來源資產中的所有關係時，List 指令最為實用。範例：這項功能可讓使用者前往相關項目。執行行動應用程式時，這項功能可讓您輕鬆瀏覽對應的網站或 Google+ 個人資料。

AndroidAppAsset

說明 Android 應用程式資產。

欄位名稱 類型 說明
package_name string Android 應用程式資產是採用 Java 套件名稱的自然識別名稱。舉例來說，Google 地圖應用程式使用套件名稱 com.google.android.apps.maps。必要
certificate CertificateInfo

由於套件名稱沒有重複性全面強制規定，因此我們要求簽署憑證，因此必須與套件名稱搭配可明確識別應用程式的套件名稱。

部分應用程式的簽署金鑰會輪替金鑰，因此日後可能會以不同的金鑰簽署。系統會將這些資產視為不同的資產，因為我們使用 (套件名稱、憑證) 做為專屬 ID。這通常不會造成問題，因為兩個版本的應用程式都會做出相同或類似的陳述。不過，輪替金鑰時，其他用來聲明應用程式相關資產的資產也必須更新。

(請注意，發布及查詢陳述式的語法包含語法糖，方便您指定由多個憑證已知的應用程式)。必要

CertificateInfo

說明 X509 憑證。

欄位名稱 類型 說明
sha256_fingerprint string

憑證的大寫 SHA-265 指紋。您可以透過以下方式取得 PEM 憑證：

$ keytool -printcert -file $CERTFILE | grep SHA256:
SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
    42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5

或按讚：

$ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
    16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5

在這個範例中，這個欄位的內容是 14:6D:E9:83:C5:73: 06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF: 44:E5。

如果您無法使用這些工具，可以先將 PEM 憑證轉換為 DER 格式，然後計算該字串的 SHA-256 雜湊，並以十六進位字串表示結果 (也就是每八位元的大寫十六進位表示法，以冒號分隔)。

資產

可用來識別資產。

數位資產是可識別身分且可定址的線上實體，通常提供部分服務或內容。例如網站、Android 應用程式、Twitter 動態消息和 Google+ 專頁。

欄位名稱 類型 說明
聯集欄位，只能擇一：
web WebAsset 是否要設為網路資產。
android_app AndroidAppAsset 設定是否為 Android 應用程式素材資源。

CheckRequest

用於檢查特定資產連結是否存在的訊息。

欄位名稱 類型 說明
source Asset 代管陳述式清單的來源。用於將 Check() 呼叫轉送至適當的來源。
relation string

關係的查詢字串。

我們會識別與 <kind>/<detail> 格式字串的關係，其中 <kind> 必須是一組預先定義的用途類別之一，而 <detail> 是任意形式的小寫英數字元字串，說明這個陳述式的特定用途。

如需目前支援的關係清單，請參閱 API 說明文件。

查詢要比對資產連結時，查詢和資產連結的關係字串必須完全相符。

範例：關聯 delegate_permission/common.handle_all_urls 的查詢符合關聯 delegate_permission/common.handle_all_urls 的資產連結。
target Asset 陳述的目標資產。

CheckResponse

CheckAssetLinks 呼叫的回應訊息。

欄位名稱 類型 說明
linked bool 如果要求中指定的資產與要求中指定的關係連結，則設為 true。必要
max_age Duration 從放送時間開始，系統會將回應視為有效停止的進一步更新時間。必要
debug_string string

人類可讀的訊息內含有助於使用者瞭解、重現及偵錯結果的資訊。

留言將會以英文撰寫，我們目前不打算提供任何翻譯。

請注意，無法保證這個字串的內容或格式。我們可能會隨時變更任何資訊，恕不另行通知。請勿嘗試透過程式輔助方式剖析這項資料。如果覺得您必須這麼做，因為該 API 不會公開您需要的資訊，請先與我們聯絡。

ListRequest

這個訊息可用來要求所有具備指定來源和關聯的已知陳述式。

欄位名稱 類型 說明
source Asset 代管陳述式清單的來源。用於將 List() 要求導向正確的來源。必要
relation string

只能使用符合指定關係的關聯。

如要進一步瞭解關聯字串的詳細定義，請參閱 Statement 訊息。

為了讓查詢比對陳述式，必須符合下列其中一項條件：

  • 查詢和陳述式的關係字串完全相符，或
  • 查詢的相關字串空白或遺失。

範例：關聯 delegate_permission/common.handle_all_urls 的查詢符合關聯 delegate_permission/common.handle_all_urls 的資產連結。

ListResponse

List 呼叫的回應訊息。

欄位名稱 類型 說明
statements Statement 已找到的所有相符陳述式的清單。
max_age Duration 從放送時間開始，系統會將回應視為有效停止的進一步更新時間。必要
debug_string string

人類可讀的訊息內含有助於使用者瞭解、重現及偵錯結果的資訊。

留言將會以英文撰寫，我們目前不打算提供任何翻譯。

請注意，無法保證這個字串的內容或格式。我們可能會隨時變更任何資訊，恕不另行通知。請勿嘗試透過程式輔助方式剖析這項資料。如果覺得您必須這麼做，因為該 API 不會公開您需要的資訊，請先與我們聯絡。

陳述式

闡述了一項符合來源資產和目標資產關聯性的可靠陳述。

聲明一律由來源資產撰寫，無論是直接處理，還是委派給儲存在其他位置的對帳單清單即可。

如需陳述式和資產的詳細定義，請參閱 API 說明文件到達網頁。

欄位名稱 類型 說明
source Asset 每個陳述式都有來源素材資源。必要
relation string

與來源資產擁有者 (也就是發布聲明的個人或實體) 按照預期的方式使用聲明。每個完整的陳述都有關聯。

我們會識別與 <kind>/<detail> 格式字串的關係，其中 <kind> 必須是一組預先定義的用途類別之一，而 <detail> 是任意形式的小寫英數字元字串，說明這個陳述式的特定用途。

如需目前支援的關係清單，請參閱 API 說明文件。

範例：必須提供 delegate_permission/common.handle_all_urls
target Asset 每個陳述式都有目標資產。必要

WebAsset

說明網路資產。

欄位名稱 類型 說明
site string

系統會透過一個網址 (只包含配置、主機名稱和通訊埠部分) 來識別網路資產。格式為

http[s]://<hostname>[:<port>]

主機名稱必須完整無誤，結尾必須為半形句號 (「.」)。

目前僅允許「http」和「https」網路配置。

通訊埠號碼是以十進位數字的形式指定，使用標準通訊埠號碼時必須省略。若使用標準通訊埠號碼，請省略 80，https 為 443。

這個有限網址稱為「site」。系統會將使用相同配置、主機名稱和通訊埠的所有網址視為網站的一部分，因此屬於網路資產。

例如，擁有 https://www.google.com 網站的素材資源包含下列所有網址：

  • https://www.google.com/
  • https://www.google.com:443/
  • https://www.google.com/foo
  • https://www.google.com/foo?bar
  • https://www.google.com/foo#bar
  • https://user@password:www.google.com/

但不包含下列網址：

  • http://www.google.com/ (錯誤配置)
  • https://google.com/ (主機名稱不相符)
  • https://www.google.com:444/ (通訊埠不符) REQUIRED