Package google.digitalassetlinks.v1

Chỉ mục

Bảng sao kê

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

Tất cả các bảng sao kê do API này trả về đã được tạo thay mặt cho các thành phần kỹ thuật số (ví dụ: trang web hoặc ứng dụng Android) về những thành phần kỹ thuật số khác. Mỗi câu lệnh chứa một tài sản nguồn, một tài sả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 nội dung như được xác nhận quyền sở hữu theo nội dung nguồn. Một ví dụ về những mối quan hệ như vậy là việc uỷ quyền đặc quyền hoặc 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 mục tiêu và chuỗi câu lệnh được chỉ định.

API đảm bảo rằng tất cả các bảng sao kê 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 tài sản tạo ra một cách an toàn, như mô tả trong thông số kỹ thuật thiết kế kỹ thuật cho Đường liên kết đến tài sản kỹ thuật số. Cụ thể là bạn nên cân nhắc việc đảm bảo các trang web không an toàn (tức là các URL bắt đầu bằng http:// thay vì https://).

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ách liên quan đến hai tài sản hoặc liệt kê tất cả mối quan hệ từ một tài sản nguồn cụ thể. Ví dụ: một tính năng giúp người dùng di chuyển đến các mục liên quan. Khi một ứng dụng dành cho thiết bị di động đang chạy trên một thiết bị, tính năng này sẽ giúp bạn dễ dàng điều hướng đến trang web tương ứng hoặc hồ sơ trên Google+.

Thành phần của ứng dụng Android

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

Tên trường Loại Mô tả
package_name string Nội dung ứ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 com.google.android.apps.maps. BẮT BUỘC
certificate CertificateInfo

Do không có quá trình thực thi duy nhất đối với tên gói, nên chúng tôi cũng yêu cầu chứng chỉ ký, cùng 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, do đó, các khoá này có thể được ký bằng các khoá khác nhau theo thời gian. Chúng tôi xem đó là những thành phầ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ùng một câu lệnh hoặc các câu lệnh tương tự. Tuy nhiên, các tài sản khác đưa ra câu lệnh về ứng dụng sẽ phải được cập nhật khi xoay vòng khóa.

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

Thông tin về chứng chỉ

Mô tả chứng chỉ X509.

Tên trường Loại Mô tả
sha256_fingerprint string

Tệp tham chiếu 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ư sau:

$ 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 dù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 đó và thể hiện kết quả dưới dạng chuỗi thập lục phân (nghĩa là các giá trị 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).

Thành phần

Nhận dạng duy nhất một thành phần.

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

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

Yêu cầu séc

Thông báo dùng để kiểm tra xem có đường liên kết đến thành phần cụ thể nào không.

Tên trường Loại Mô tả
source Asset Nguồn lưu trữ danh sách câu lệnh. Thông tin này được dùng để chuyển lệnh gọi Check() đến nguồn thích hợp.
relation string

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

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

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 cụm từ tìm kiếm khớp với một đường liên kết đến tài sản, cả chuỗi quan hệ của cụm từ tìm kiếm đó và chuỗi đường liên kết đến tài sản đều phải khớp chính xác.

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

Phản hồi kiểm tra

Thông báo phản hồi cho lệnh gọi CheckAssetLink.

Tên trường Loại Mô tả
linked bool Đặt thành true nếu các thành phần được chỉ định trong yêu cầu được liên kết bằng mối quan hệ được chỉ định trong yêu cầu. BẮT BUỘC
max_age Duration Kể từ thời gian phân phát, thời hạn phản hồi sẽ được coi là hợp lệ nếu không được cập nhật thêm. BẮT BUỘC
debug_string string

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

Thông báo này sẽ bằng tiếng Anh và chúng tôi hiện không dự định 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 hay định dạng của chuỗi này. Mọi khía cạnh của dữ liệu này có thể thay đổi mà không cần thông báo trước. 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 cảm thấy cần phải làm điều này vì thông tin bạn cần không bị API tiết lộ, trước tiên, vui lòng liên hệ với chúng tôi.

ListRequest (Yêu cầu về danh sách)

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ệ được chỉ định.

Tên trường Loại Mô tả
source Asset Nguồn lưu trữ danh sách câu lệnh. Thông tin 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 liên kết phù hợp với mối quan hệ được chỉ định.

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

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

  • cả chuỗi quan hệ của cụm từ tìm kiếm 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ụ: Một truy vấn có mối quan hệ delegate_permission/common.handle_all_urls khớp với một đường liên kết tài sản có mối quan hệ delegate_permission/common.handle_all_urls.

ListResponse

Thông báo phản hồi cho lệnh gọi Danh sách.

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

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

Thông báo này sẽ bằng tiếng Anh và chúng tôi hiện không dự định 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 hay định dạng của chuỗi này. Mọi khía cạnh của dữ liệu này có thể thay đổi mà không cần thông báo trước. 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 cảm thấy cần phải làm điều này vì thông tin bạn cần không bị API tiết lộ, trước tiên, vui lòng liên hệ với chúng tôi.

Tuyên bố

Mô tả câu lệnh đáng tin cậy được đưa ra về mối quan hệ giữa tài sản nguồn và tài sản mục tiêu.

Những câu lệnh luôn được tạo bằng tài sản nguồn, trực tiếp hoặc bằng cách uỷ quyền cho một danh sách câu lệnh được lưu trữ ở nơi khác.

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

Tên trường Loại Mô tả
source Asset Mỗi câu lệnh đều có một tài sả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 chủ định của chủ sở hữu tài sản nguồn (tức là người hoặc pháp nhân đưa ra câu lệnh). Mỗi câu lệnh hoàn chỉnh đều có mối quan hệ.

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

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 BẮT BUỘC
target Asset Mỗi câu lệnh đều có nội dung mục tiêu. BẮT BUỘC

Tài sản web

Mô tả một tài sản web.

Tên trường Loại Mô tả
site string

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

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

Tên máy chủ phải đủ điều kiện: chúng phải kết thúc bằng một dấu chấm (".").

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ử dụng số cổng tiêu chuẩn: 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 đều được coi là một phần của trang web và do đó thuộc về tài sản web.

Ví dụ: thành phần có 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/

Nhưng không chứa các URL sau:

  • http://www.google.com/ (lược đồ không chính xác)
  • https://google.com/ (tên máy chủ không khớp)
  • https://www.google.com:444/ (cổng không khớp) REQUIRED