Package google.digitalassetlinks.v1

Indeks

Oświadczenia

Ta usługa interfejsu API udostępnia „wyciągi”, czyli pojazdy używane przez właścicieli zasobów do publikowania informacji o linkach do zasobów. Interfejs API może być używany do pobierania instrukcji w prosty i bezpieczny sposób bez konieczności pobierania instrukcji bezpośrednio ze źródeł.

Wszystkie oświadczenia zwrócone przez ten interfejs API zostały wygenerowane w imieniu zasobów cyfrowych (np. witryn lub aplikacji na Androida) dotyczących innych zasobów cyfrowych. Każda instrukcja zawiera zasób źródłowy, docelowy i co najmniej 1 relację.

Relacja opisuje relację między dwoma zasobami zgodnie z roszczeniem dotyczącym zasobu źródłowego. Przykładem takich relacji jest przekazywanie uprawnień lub uprawnień.

Lista

rpc List(ListRequest) returns (ListResponse)

Pobiera z danego źródła listę wszystkich instrukcji, które pasują do określonego ciągu docelowego i ciągu instrukcji.

Interfejs API gwarantuje, że wszystkie instrukcje z zasobami zabezpieczonymi źródłowymi, takie jak witryny HTTPS lub aplikacje na Androida, zostały wykonane w bezpieczny sposób przez właściciela tych zasobów, zgodnie ze specyfikacją techniczną linków do zasobów cyfrowych. Pamiętaj, że w przypadku niezabezpieczonych witryn (czyli takich, których adres URL zaczyna się od http:// zamiast https://) nie można zagwarantować takiej gwarancji.

Polecenie List jest najbardziej przydatne, gdy klient interfejsu API chce poznać wszystkie sposoby, na jakie dwa zasoby są ze sobą powiązane, lub wyliczyć wszystkie relacje z określonego zasobu źródłowego. Przykład: funkcja, która pomaga użytkownikom przejść do powiązanych elementów. Gdy aplikacja mobilna działa na urządzeniu, funkcja ta ułatwia przechodzenie do odpowiedniej witryny lub profilu Google+.

AndroidAppAsset

Opisuje zasób aplikacji na Androida.

Nazwa pola Typ Opis
package_name string Zasoby aplikacji na Androida są zwykle identyfikowane po nazwie pakietu Javy. Na przykład aplikacja Mapy Google używa nazwy pakietu com.google.android.apps.maps. WYMAGANE
certificate CertificateInfo

Nie ma globalnego egzekwowania zasad dotyczących niepowtarzalności nazwy pakietu, dlatego wymagamy również certyfikatu podpisywania, który w połączeniu z nazwą pakietu jednoznacznie identyfikuje aplikację.

Klucze podpisywania niektórych aplikacji podlegają rotacji, więc z czasem mogą być podpisywane innymi kluczami. Traktujemy je jako oddzielne zasoby, ponieważ wykorzystujemy (nazwa pakietu, certyfikat) jako unikalny identyfikator. Zazwyczaj nie powinno to sprawiać problemów, ponieważ obie wersje aplikacji zawierają takie same lub podobne stwierdzenia. Inne komponenty zawierające stwierdzenia o aplikacji muszą być jednak aktualizowane podczas rotacji klucza.

Pamiętaj, że składnia instrukcji publikowania i wysyłania zapytań o instrukcje zawiera cukier składowy, który ułatwia określenie aplikacji znanych z wielu certyfikatów. WYMAGANE

CertificateInfo

Opis certyfikatu X509.

Nazwa pola Typ Opis
sha256_fingerprint string

Odcisk cyfrowy certyfikatu pisany wielkimi literami przy użyciu algorytmu SHA-265. Certyfikat PEM można uzyskać w ten sposób:

$ 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

lub podobny:

$ 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

W tym przykładzie zawartość tego pola to 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.

Jeśli nie masz dostępu do tych narzędzi, możesz przekonwertować certyfikat PEM na format DER, obliczyć hasz SHA-256 tego ciągu i zapisać wynik w postaci szesnastkowego ciągu (czyli reprezentacji każdego oktetu w systemie szesnastkowym wielkimi literami, rozdzielanych dwukropkiem).

Zasób

Jednoznacznie identyfikuje zasób.

Zasób cyfrowy to możliwy do zidentyfikowania i dostosowania podmiot internetowy, który zwykle oferuje określone usługi lub treści. Przykładami zasobów są witryny, aplikacje na Androida, kanały na Twitterze i strony Plus.

Nazwa pola Typ Opis
sumy, tylko jedna z tych wartości:
web WebAsset Ustaw, jeśli jest to komponent internetowy.
android_app AndroidAppAsset Ustaw, jeśli jest to komponent aplikacji na Androida.

CheckRequest

Komunikat używany do sprawdzenia, czy istnieje określony link do zasobu.

Nazwa pola Typ Opis
source Asset Źródło hostujące listę instrukcji. Służy do kierowania wywołania funkcji Check() do odpowiedniego źródła.
relation string

Ciąg zapytania dla relacji.

Identyfikujemy relacje z ciągami znaków w formacie <kind>/<detail>, gdzie <kind> musi być jedną ze wstępnie zdefiniowanych kategorii przeznaczenia, a <detail> to swobodny ciąg alfanumeryczny, który opisuje określony przypadek użycia wyrażenia.

Bieżącą listę obsługiwanych relacji znajdziesz w dokumentacji interfejsu API.

Aby zapytanie odpowiadało linkowi do zasobu, ciągi relacji w zapytaniu i linku do zasobu muszą być dokładnie takie same.

Przykład: zapytanie z relacją delegate_permission/common.handle_all_urls pasuje do linku zasobu z relacją delegate_permission/common.handle_all_urls.
target Asset Docelowy komponent wyciągu.

CheckResponse

Komunikat z odpowiedzią na wywołanie CheckAssetLinks.

Nazwa pola Typ Opis
linked bool Ustaw wartość „true” (prawda), jeśli zasoby określone w żądaniu są połączone przez relację określoną w żądaniu. WYMAGANE
max_age Duration Po jakim czasie od wyświetlenia odpowiedź ma być uznawana za prawidłową, z wyłączeniem dalszych aktualizacji. WYMAGANE
debug_string string

Zrozumiały dla człowieka komunikat zawierający informacje, które pomogą użytkownikom zrozumieć, odtworzyć i debugować wynik.

Wiadomość będzie w języku angielskim. Obecnie nie planujemy oferować żadnych tłumaczeń.

Pamiętaj, że nie możemy zagwarantować co najmniej 1 z treści ani formatu tego ciągu znaków. Jego każdy aspekt może ulec zmianie bez powiadomienia. Nie należy podejmować prób programowej analizy tych danych. Jeśli uważasz, że musisz to zrobić, ponieważ informacje, których potrzebujesz, nie są ujawniane przez interfejs API, najpierw skontaktuj się z nami.

ListRequest

Wiadomość używana do żądania wszystkich znanych instrukcji, które mają określone źródło i relację.

Nazwa pola Typ Opis
source Asset Źródło hostujące listę instrukcji. Służą do kierowania żądania List() do właściwego źródła. WYMAGANE
relation string

Używaj tylko powiązań, które pasują do określonej relacji.

Szczegółową definicję ciągów relacji znajdziesz w komunikacie Statement.

Aby zapytanie zostało dopasowane do wyrażenia, musi być spełniony jeden z tych warunków:

  • ciągi relacji zapytania i wyrażenia są dokładnie dopasowane, lub
  • ciąg relacji zapytania jest pusty lub brakuje w nim ciągu znaków.

Przykład: zapytanie z relacją delegate_permission/common.handle_all_urls pasuje do linku zasobu z relacją delegate_permission/common.handle_all_urls.

ListResponse

Komunikat z odpowiedzią na wywołanie listy.

Nazwa pola Typ Opis
statements Statement Lista wszystkich pasujących instrukcji.
max_age Duration Po jakim czasie od wyświetlenia odpowiedź ma być uznawana za prawidłową, z wyłączeniem dalszych aktualizacji. WYMAGANE
debug_string string

Zrozumiały dla człowieka komunikat zawierający informacje, które pomogą użytkownikom zrozumieć, odtworzyć i debugować wynik.

Wiadomość będzie w języku angielskim. Obecnie nie planujemy oferować żadnych tłumaczeń.

Pamiętaj, że nie możemy zagwarantować co najmniej 1 z treści ani formatu tego ciągu znaków. Jego każdy aspekt może ulec zmianie bez powiadomienia. Nie należy podejmować prób programowej analizy tych danych. Jeśli uważasz, że musisz to zrobić, ponieważ informacje, których potrzebujesz, nie są ujawniane przez interfejs API, najpierw skontaktuj się z nami.

Instrukcja

Opisuje rzetelne stwierdzenie dotyczące relacji między zasobem źródłowym a docelowym.

Instrukcje są zawsze tworzone przez zasób źródłowy – bezpośrednio lub przez przekazanie do listy instrukcji przechowywanej w innym miejscu.

Bardziej szczegółowe definicje wyciągów i komponentów znajdziesz na stronie dokumentacji interfejsu API.

Nazwa pola Typ Opis
source Asset Każda instrukcja zawiera zasób źródłowy. WYMAGANE
relation string

Relacja określa użycie wyrażenia przez właściciela zasobu źródłowego (czyli osobę lub podmiot, który je wydał). Każde pełne wyrażenie ma swój związek.

Identyfikujemy relacje z ciągami znaków w formacie <kind>/<detail>, gdzie <kind> musi być jedną ze wstępnie zdefiniowanych kategorii przeznaczenia, a <detail> to swobodny ciąg alfanumeryczny, który opisuje określony przypadek użycia wyrażenia.

Bieżącą listę obsługiwanych relacji znajdziesz w dokumentacji interfejsu API.

Przykład: delegate_permission/common.handle_all_urls REQUIRED
target Asset Każde wyrażenie zawiera zasób docelowy. WYMAGANE

WebAsset

Opisuje zasób internetowy.

Nazwa pola Typ Opis
site string

Zasoby internetowe są identyfikowane na podstawie adresu URL, który zawiera tylko schemat, nazwę hosta i części portu. Format to

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

Nazwy hostów muszą być w pełni kwalifikowane: muszą kończyć się pojedynczym kropką („.”).

Obecnie dozwolone są tylko schematy „http” i „https”.

Numery portów są podawane w formacie dziesiętnym. Jeśli używasz standardowych numerów portów, należy je pominąć: 80 w przypadku protokołu http i 443 dla protokołu https.

Ten ograniczony adres URL nazywamy „witryną”. Wszystkie adresy URL o tym samym schemacie, tej samej nazwie hosta i portu są uznawane za część witryny i dlatego należą do zasobu internetowego.

Przykład: zasób z witryną https://www.google.com zawiera wszystkie te adresy URL:

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

Nie zawiera jednak tych adresów URL:

  • http://www.google.com/ (nieprawidłowy schemat)
  • https://google.com/ (niezgodna nazwa hosta)
  • https://www.google.com:444/ (niezgodny port) WYMAGANE