Package google.digitalassetlinks.v1

Chỉ mục

Tuyên bố

Dịch vụ API này phân phát "tuyên bố", tức là những phương tiện mà chủ sở hữu tài sản dùng để đăng thông tin về các đường liên kết đến tài sản của họ. Bạn có thể sử dụng API này để truy xuất câu lệnh theo cách đơn giản và bảo mật mà không cần lấy câu lệnh trực tiếp từ nguồn.

Tất cả nội dung tuyên bố mà API này trả về đã được đưa ra thay mặt cho tài sản kỹ thuật số (ví dụ: trang web hoặc ứng dụng Android) về các tài sản kỹ thuật số khác. Mỗi câu lệnh chứa một thành phần nguồn, một thành phần mục tiêu và một hoặc nhiều mối quan hệ.

Mối quan hệ mô tả mối quan hệ giữa hai tài sản như được xác nhận quyền sở hữu theo tài sản nguồn. Một ví dụ cho các mối quan hệ như vậy là việc uỷ quyền đặc quyền hoặc cấp quyền.

Danh sách

rpc List(ListRequest) returns (ListResponse)

Truy xuất danh sách tất cả câu lệnh từ một nguồn nhất định khớp với chuỗi câu lệnh và mục tiêu đã chỉ định.

API này đảm bảo rằng tất cả câu lệnh có tài sản nguồn bảo mật (chẳng hạn như trang web HTTPS hoặc ứng dụng Android) đều đã được chủ sở hữu của những tài sản đó đưa ra một cách an toàn, theo mô tả trong quy cách thiết kế kỹ thuật của Digital Asset Links (Đường liên kết đến tài sản kỹ thuật số). Cụ thể, bạn nên lưu ý rằng đối với các trang web không an toàn (tức là nơi URL bắt đầu bằng http:// thay vì https://), bạn không thể thực hiện đảm bảo này.

Lệnh List hữu ích nhất trong trường hợp ứng dụng API muốn biết tất cả các mối liên hệ giữa hai tài sản hoặc liệt kê tất cả các mối quan hệ từ một tài sản nguồn cụ thể. Ví dụ: tính năng giúp người dùng chuyển đến các mục có liên quan. Khi ứng dụng dành cho thiết bị di động đang chạy trên thiết bị, tính năng này sẽ giúp điều hướng dễ dàng đến trang web hoặc hồ sơ trên Google+ tương ứng.

AndroidAppAsset

Mô tả thành phần ứng dụng Android.

Tên trường Loại Nội dung mô tả
package_name string Thành phần Ứng dụng Android được xác định tự nhiên theo tên gói Java. Ví dụ: ứng dụng Google Maps sử dụng tên gói là com.google.android.apps.maps. BẮT BUỘC
certificate CertificateInfo

Do không có quy tắc thực thi trên toàn cầu đối với tính duy nhất của tên gói, nên chúng tôi cũng yêu cầu chứng chỉ ký, kết hợp với tên gói giúp xác định duy nhất một ứng dụng.

Khoá ký của một số ứng dụng được xoay vòng nên có thể được ký bằng các khoá khác nhau theo thời gian. Chúng tôi coi những tài sản này là tài sản riêng biệt vì chúng tôi sử dụng (tên gói, chứng chỉ) làm mã nhận dạng duy nhất. Điều này thường không gây ra bất kỳ vấn đề nào vì cả hai phiên bản ứng dụng sẽ đưa ra các tuyên bố giống nhau hoặc tương tự nhau. Tuy nhiên, những thành phần khác đưa ra tuyên bố về ứng dụng sẽ phải được cập nhật khi xoay vòng khoá.

(Lưu ý rằng cú pháp để xuất bản và truy vấn các câu lệnh có chứa cú pháp dễ hiểu để bạn dễ dàng chỉ định các ứng dụng mà nhiều chứng chỉ biết đến.) BẮT BUỘC

CertificateInfo

Mô tả chứng chỉ X509.

Tên trường Loại Nội dung mô tả
sha256_fingerprint string

Dấu vân tay SHA-265 viết hoa của chứng chỉ. Bạn có thể lấy chứng chỉ PEM như sau:

$ 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

hoặc như thế này:

$ 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

Trong ví dụ này, nội dung của trường này sẽ là 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.

Nếu không có các công cụ này, bạn có thể chuyển đổi chứng chỉ PEM sang định dạng DER, tính toán hàm băm SHA-256 của chuỗi đó rồi biểu diễn kết quả dưới dạng chuỗi hex (tức là biểu diễn thập lục phân viết hoa của từng octet, phân tách bằng dấu hai chấm).

Tài sản

Xác định duy nhất một tài sản.

Tài sản kỹ thuật số là một pháp nhân trực tuyến có thể nhận dạng và xác định địa chỉ, thường cung cấp một số dịch vụ hoặc nội dung. Ví dụ về các thành phần: trang web, ứng dụng Android, nguồn cấp dữ liệu Twitter và Plus Pages.

Tên trường Loại Nội dung mô tả
Trường kết hợp, chỉ có một trong các trường sau:
web WebAsset Thiết lập nếu đây là thành phần trên web.
android_app AndroidAppAsset Đặt nếu đây là thành phần Ứng dụng Android.

CheckRequest

Thông báo dùng để kiểm tra sự tồn tại của một đường liên kết đến tài sản cụ thể.

Tên trường Loại Nội dung mô tả
source Asset Nguồn lưu trữ danh sách bảng sao kê. Mã này dùng để định tuyến lệnh gọi Check() đến nguồn phù hợp.
relation string

Chuỗi truy vấn cho mối quan hệ.

Chúng ta xác định mối quan hệ bằng các chuỗi có định dạng <kind>/<detail>, trong đó <kind> phải là một trong tập hợp các danh mục mục đích được xác định trước và <detail> là một chuỗi chữ và số viết thường dạng tự do mô tả trường hợp sử dụng cụ thể của câu lệnh.

Hãy tham khảo tài liệu về API của chúng tôi để biết danh sách các mối quan hệ được hỗ trợ hiện tại.

Để một truy vấn khớp với đường liên kết tài sản, chuỗi quan hệ của cụm từ tìm kiếm và đường liên kết tài sản phải khớp chính xác.

Ví dụ: Truy vấn có quan hệ delegate_permission/common.handle_all_urls khớp với một đường liên kết đến tài sản có quan hệ delegate_permission/common.handle_all_urls.
target Asset Thành phần mục tiêu của câu lệnh.

CheckResponse

Thông báo phản hồi cho cuộc gọi CheckAssetLinks.

Tên trường Loại Nội dung mô tả
linked bool Đặt thành đúng nếu những thành phần được chỉ định trong yêu cầu được liên kết theo mối quan hệ được chỉ định trong yêu cầu. BẮT BUỘC
max_age Duration Từ thời gian phân phát, khoảng thời gian dài hơn mà phản hồi đó được coi là hợp lệ nếu không cập nhật thêm. BẮT BUỘC
debug_string string

Thông báo mà con người có thể đọc được, có chứa thông tin nhằm giúp người dùng cuối hiểu, tái tạo và gỡ lỗi kết quả.

Thông báo này sẽ bằng tiếng Anh và hiện tại chúng tôi không có kế hoạch cung cấp bản dịch.

Xin lưu ý rằng chúng tôi không đảm bảo về nội dung hoặc định dạng của chuỗi này. Bất kỳ khía cạnh nào của nội dung có thể thay đổi mà không cần thông báo. Bạn không nên tìm cách phân tích cú pháp dữ liệu này theo phương thức lập trình. Nếu bạn thấy cần phải làm việc này vì thông tin bạn cần không được API hiển thị, vui lòng liên hệ trước với chúng tôi.

ListRequest

Thông báo dùng để yêu cầu tất cả câu lệnh đã biết có nguồn và mối quan hệ đã chỉ định.

Tên trường Loại Nội dung mô tả
source Asset Nguồn lưu trữ danh sách bảng sao kê. Hàm này dùng để chuyển yêu cầu List() đến đúng nguồn. BẮT BUỘC
relation string

Chỉ sử dụng các mối liên kết phù hợp với mối quan hệ đã chỉ định.

Hãy xem thông báo Statement để biết định nghĩa chi tiết về chuỗi quan hệ.

Để một truy vấn khớp với câu lệnh, một trong các điều kiện sau phải đúng:

  • cả chuỗi quan hệ của truy vấn và câu lệnh đều khớp chính xác, hoặc
  • chuỗi quan hệ của truy vấn bị trống hoặc bị thiếu.

Ví dụ: Truy vấn có quan hệ delegate_permission/common.handle_all_urls khớp với một đường liên kết đến tài sản có quan hệ delegate_permission/common.handle_all_urls.

ListResponse

Tin nhắn phản hồi cho cuộc gọi Danh sách.

Tên trường Loại Nội dung mô tả
statements Statement Danh sách tất cả câu lệnh trùng khớp đã được tìm thấy.
max_age Duration Từ thời gian phân phát, khoảng thời gian dài hơn mà phản hồi đó được coi là hợp lệ nếu không cập nhật thêm. BẮT BUỘC
debug_string string

Thông báo mà con người có thể đọc được, có chứa thông tin nhằm giúp người dùng cuối hiểu, tái tạo và gỡ lỗi kết quả.

Thông báo này sẽ bằng tiếng Anh và hiện tại chúng tôi không có kế hoạch cung cấp bản dịch.

Xin lưu ý rằng chúng tôi không đảm bảo về nội dung hoặc định dạng của chuỗi này. Bất kỳ khía cạnh nào của nội dung có thể thay đổi mà không cần thông báo. Bạn không nên tìm cách phân tích cú pháp dữ liệu này theo phương thức lập trình. Nếu bạn thấy cần phải làm việc này vì thông tin bạn cần không được API hiển thị, vui lòng liên hệ trước với chúng tôi.

Tuyên bố

Mô tả tuyên bố đáng tin cậy về mối quan hệ giữa nội dung nguồn và nội dung mục tiêu.

Nội dung tuyên bố luôn được tạo bởi nội dung nguồn, có thể là trực tiếp hoặc uỷ quyền cho một danh sách bảng sao kê được lưu trữ ở nơi khác.

Để biết định nghĩa chi tiết hơn về bảng sao kê và thành phần, vui lòng tham khảo trang đích của tài liệu API.

Tên trường Loại Nội dung mô tả
source Asset Mỗi câu lệnh đều có một thành phần nguồn. BẮT BUỘC
relation string

Mối quan hệ này xác định việc sử dụng câu lệnh theo dự định của chủ sở hữu nội dung nguồn (tức là cá nhân hoặc pháp nhân phát hành câu lệnh). Mỗi câu lệnh hoàn chỉnh đều có một mối quan hệ.

Chúng ta xác định mối quan hệ bằng các chuỗi có định dạng <kind>/<detail>, trong đó <kind> phải là một trong tập hợp các danh mục mục đích được xác định trước và <detail> là một chuỗi chữ và số viết thường dạng tự do mô tả trường hợp sử dụng cụ thể của câu lệnh.

Hãy tham khảo tài liệu về API của chúng tôi để biết danh sách các mối quan hệ được hỗ trợ hiện tại.

Ví dụ: delegate_permission/common.handle_all_urls REQUIRED
target Asset Mỗi câu lệnh đều có một thành phần mục tiêu. BẮT BUỘC

WebAsset

Mô tả tài sản trên web.

Tên trường Loại Nội dung mô tả
site string

Thành phần web được xác định bằng một URL chỉ chứa giao thức, tên máy chủ và các phần của cổng. Định dạng là

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

Tên máy chủ phải đủ điều kiện: tên máy chủ phải kết thúc trong một khoảng thời gian (".").

Hiện chỉ cho phép các giao thức "http" và "https".

Số cổng được cung cấp dưới dạng số thập phân và phải được bỏ qua nếu số cổng tiêu chuẩn được sử dụng: 80 cho http và 443 cho https.

Chúng tôi gọi URL bị giới hạn này là "trang web". Tất cả URL có cùng lược đồ, tên máy chủ và cổng được xem là một phần của trang web và do đó thuộc về thành phần web.

Ví dụ: thành phần với trang web https://www.google.com chứa tất cả các URL sau:

  • 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/

Tuy nhiên, tài sản này không chứa các URL sau:

  • http://www.google.com/ (sai lược đồ)
  • https://google.com/ (tên máy chủ không khớp)
  • https://www.google.com:444/ (cổng không khớp) BẮT BUỘC