Package google.digitalassetlinks.v1

索引

陳述式

這個 API 服務提供「陳述式」，也就是資產擁有者用來發布資產連結相關資訊的車輛。這個 API 可讓您輕鬆又安全地擷取陳述式，不需要直接從來源取得陳述式。

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

關係說明瞭來源資產已聲明版權的兩項資產之間的關係。舉例來說，委派權限或權限代表這類關係。

清單

rpc List(ListRequest) returns (ListResponse)

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

根據《Digital Asset Links 技術設計規格》的規定，API 可確保所有含有安全來源資產 (例如 HTTPS 網站或 Android 應用程式) 的聲明都以安全的方式產生，請特別注意，如果是不安全的網站 (也就是網址開頭是 http:// 而非 https://)，就無法保證這些資訊。

如果 API 用戶端想要瞭解兩個資產間的關係，或列舉特定來源資產的所有關係，List 指令就能派上用場。範例：可協助使用者前往相關項目的功能。在裝置上執行行動應用程式時，您可透過這項功能輕鬆前往相對應的網站或 Google+ 個人資料。

Android 應用程式素材資源

用於說明 Android 應用程式資產。

欄位名稱 類型 說明
package_name string Android 應用程式素材資源可由其 Java 套件名稱自然辨識。舉例來說，Google 地圖應用程式使用套件名稱 com.google.android.apps.maps，必填
certificate CertificateInfo

我們並未強制對套件名稱強制執行全球性政策，我們也要求簽署憑證，且必須搭配套件名稱，才能識別應用程式。

某些應用程式的簽署金鑰會經過輪替，因此可能會隨著不同的金鑰簽署。系統會將這些資產視為唯一的 ID，因為我們使用 (套件名稱、憑證) 做為專屬 ID。這通常不會造成任何問題，因為兩個版本的應用程式都會產生相同或類似的陳述式。但是，當金鑰旋轉時，需要更新應用程式的其他資產必須更新。

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

憑證資訊

描述 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 動態饋給和專頁。

欄位名稱 類型 說明
欄位的值，只能填入下列其中一個值：
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 未對外公開您需要的資訊，請自行與我們聯絡。

清單要求

用來要求所有具有指定來源和關係的已知陳述式的訊息。

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

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

如需關係字串的詳細定義，請參閱 Statement 訊息。

查詢必須符合下列其中一項條件才能符合陳述式：

  • 查詢與陳述式的關係字串完全相符，或是
  • 查詢的關係字串為空白或遺漏。

範例：關係為 delegate_permission/common.handle_all_urls 的查詢與與 delegate_permission/common.handle_all_urls 關係的資產連結相符。

ListResponse

清單呼叫的回應訊息。

欄位名稱 類型 說明
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 每個陳述式都有一個目標資產。必填

網路資產

說明網路資產。

欄位名稱 類型 說明
site string

網址所標的網址僅包含配置、主機名稱和通訊埠部分。格式為

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

主機名稱必須是完整的名稱，且必須以單一半形句號 (「.」) 結尾。

目前只允許使用配置「http」和「https」。

通訊埠號碼會以十進位數字的形式提供，使用標準通訊埠號碼時，必須省略這些數字：http 為 80，https 為 443。

這個有限網址就稱為「網站」。凡是具有相同配置、主機名稱和通訊埠的網址，都會被視為網站的一部分，因此屬於網站資產。

範例：含有 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