Package google.digitalassetlinks.v1

Indeks

Wyciągi

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

Wszystkie oświadczenia zwrócone przez ten interfejs API zostały sporządzone 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, zasób docelowy i co najmniej 1 relację.

Relacja opisuje relację między tymi 2 zasobami, których dotyczy roszczenie przez zasób źródłowy. Przykładem może być przekazywanie uprawnień.

Lista

rpc List(ListRequest) returns (ListResponse)

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

Interfejs API gwarantuje, że wszystkie oświadczenia z bezpiecznymi zasobami źródłowymi, takie jak witryny HTTPS lub aplikacje na Androida, zostały bezpiecznie utworzone przez właściciela tych zasobów, zgodnie z specyfikacją techniczną linków do zasobów cyfrowych. W szczególności pamiętaj, że w przypadku niezabezpieczonych witryn (których adres URL zaczyna się od http:// zamiast https://), nie można tego zagwarantować.

Polecenie List jest najbardziej przydatne w przypadkach, gdy klient API chce poznać wszystkie sposoby powiązania 2 zasobów lub wyliczyć wszystkie relacje z danego zasobu źródłowego. Przykład: funkcja ułatwiająca użytkownikom przechodzenie do powiązanych elementów Gdy aplikacja mobilna działa na urządzeniu, funkcja ułatwia poruszanie się w odpowiedniej witrynie internetowej lub na profilu Google+.

Komponent AndroidAppAsset

Opisuje zasób aplikacji na Androida.

Nazwa pola Typ Opis
package_name string Zasoby aplikacji na Androida są w naturalny sposób identyfikowane przez nazwę pakietu Java. Na przykład aplikacja Mapy Google używa nazwy pakietu com.google.android.apps.maps. WYMAGANE
certificate CertificateInfo

Nie ma globalnego egzekwowania unikalnoś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 są poddawane rotacji, więc z czasem mogą być podpisywane przez różne klucze. Są one traktowane jako oddzielne zasoby, ponieważ używamy unikalnego identyfikatora (nazwa pakietu, certyfikat). Nie powinno to zwykle powodować żadnych problemów, ponieważ obie wersje aplikacji zawierają te same lub podobne stwierdzenia. Inne zasoby z wyrażeniami na temat aplikacji będą jednak wymagać aktualizacji po rotacji klucza.

(Pamiętaj, że składnia używana do publikowania i zapytań związanych z informacjami zawiera cukier składowy, co pozwala łatwo rozpoznawać aplikacje znane z wielu certyfikatów). WYMAGANE

Informacje o certyfikacie

Opisuje certyfikat X509.

Nazwa pola Typ Opis
sha256_fingerprint string

Odcisk cyfrowy dużego certyfikatu 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 tak:

$ 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 będzie 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 te narzędzia nie są dla Ciebie dostępne, możesz przekonwertować certyfikat PEM na format DER, oblicz hasz SHA-256 tego ciągu i przedstaw wynik w postaci szesnastkowej (czyli szesnastkowych wartościach reprezentujących każdy oktet, rozdzielonych dwukropkiem).

Komponent

Jednoznacznie identyfikuje zasób.

Zasób cyfrowy to możliwy do zidentyfikowania i adresowy podmiot online, który zwykle udostępnia niektóre usługi lub treści. Przykładowe zasoby to witryny, aplikacje na Androida, kanały na Twitterze i strony plus.

Nazwa pola Typ Opis
Unia Europejska – tylko jedno z tych pól:
web WebAsset Ustaw, jeśli jest to zasób internetowy.
android_app AndroidAppAsset Ustaw, jeśli jest to komponent aplikacji na Androida.

Żądanie Check

Komunikat używany do sprawdzania, czy istnieje link do określonego zasobu.

Nazwa pola Typ Opis
source Asset Źródło hostującej listę wyciągów. Służy ona do kierowania wywołania Check() do właściwego źródła.
relation string

Ciąg zapytania dla relacji.

Identyfikujemy powiązania z ciągami znaków w formacie <kind>/<detail>, gdzie <kind> musi być jedną ze zdefiniowanych wstępnie kategorii, a <detail> to dowolny ciąg znaków alfanumerycznych, który opisuje konkretny przypadek użycia wyrażenia.

Aktualną listę obsługiwanych relacji znajdziesz w naszej dokumentacji interfejsu API.

Aby zapytanie pasowało do linku do zasobu, obydwa ciągi muszą być identyczne.

Przykład: zapytanie o relacji delegate_permission/common.handle_all_urls pasuje do linku do zasobu o relacji delegate_permission/common.handle_all_urls.
target Asset Zasób docelowy wyciągu.

Sprawdzanie odpowiedzi

Odpowiedź na wywołanie CheckAssetLinks.

Nazwa pola Typ Opis
linked bool Ustaw wartość „true”, jeśli zasoby określone w żądaniu są połączone relacją określoną w żądaniu. WYMAGANE
max_age Duration Od momentu wyświetlenia odpowiedź powinna być uznawana za prawidłową, o ile jest ona uzasadniona. WYMAGANE
debug_string string

Czytelna dla człowieka wiadomość zawierająca informacje, które pomagają użytkownikom zrozumieć, odtworzyć i debugować wynik.

Wiadomość będzie w języku angielskim i nie planujemy udostępnić żadnych tłumaczeń.

Pamiętaj, że nie gwarantujemy zawartości ani formatu tego ciągu znaków. Każdy aspekt usługi może ulec zmianie bez powiadomienia. Nie próbuj automatycznie analizować tych danych. Jeśli uważasz, że musisz to zrobić, ponieważ interfejs API nie zapewnia dostępu do potrzebnych informacji, najpierw skontaktuj się z nami.

Żądanie dotyczące listy

Wiadomość wykorzystywana 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ącej listę wyciągów. Służy ona do kierowania żądania List() do właściwego źródła. WYMAGANE
relation string

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

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

Aby zapytanie pasowało do instrukcji, musi być spełniony jeden z tych warunków:

  • zarówno ciągi relacji zapytania, jak i wyrażenia są identyczne, lub
  • brak ciągu znaków zapytania lub jest on pusty.

Przykład: zapytanie o relacji delegate_permission/common.handle_all_urls pasuje do linku do zasobu o relacji delegate_permission/common.handle_all_urls.

Odpowiedź listy

Odpowiedź na wywołanie listy.

Nazwa pola Typ Opis
statements Statement Lista wszystkich znalezionych dopasowań stwierdzeń.
max_age Duration Od momentu wyświetlenia odpowiedź powinna być uznawana za prawidłową, o ile jest ona uzasadniona. WYMAGANE
debug_string string

Czytelna dla człowieka wiadomość zawierająca informacje, które pomagają użytkownikom zrozumieć, odtworzyć i debugować wynik.

Wiadomość będzie w języku angielskim i nie planujemy udostępnić żadnych tłumaczeń.

Pamiętaj, że nie gwarantujemy zawartości ani formatu tego ciągu znaków. Każdy aspekt usługi może ulec zmianie bez powiadomienia. Nie próbuj automatycznie analizować tych danych. Jeśli uważasz, że musisz to zrobić, ponieważ interfejs API nie zapewnia dostępu do potrzebnych informacji, najpierw skontaktuj się z nami.

Instrukcja

Przedstawia rzetelne stwierdzenie na temat zależności między zasobem źródłowym a zasobem docelowym.

Wyciągi są zawsze składane przez zasób źródłowy – bezpośrednio lub przez przekazanie dostępu do listy zapisanych gdzie indziej.

Bardziej szczegółowe definicje wyciągów i zasobó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 wskazuje sposób, w jaki zostanie on użyty przez właściciela zasobu źródłowego, czyli osobę, która je wydała. Każde stwierdzenie ma związek.

Identyfikujemy powiązania z ciągami znaków w formacie <kind>/<detail>, gdzie <kind> musi być jedną ze zdefiniowanych wstępnie kategorii, a <detail> to dowolny ciąg znaków alfanumerycznych, który opisuje konkretny przypadek użycia wyrażenia.

Aktualną listę obsługiwanych relacji znajdziesz w naszej dokumentacji interfejsu API.

Przykład: delegate_permission/common.handle_all_urls WYMAGANE
target Asset Każda instrukcja zawiera zasób docelowy. WYMAGANE

Zasób internetowy

Opisuje zasób internetowy.

Nazwa pola Typ Opis
site string

Zasoby internetowe są identyfikowane na podstawie adresu URL zawierającego tylko schemat, nazwę hosta i części portów. Format to

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

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

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

Numery portów podawane są w postaci numeru dziesiętnego i trzeba je pominąć, jeśli są używane standardowe numery portów: 80 dla http i 443 dla https.

Ten ograniczony adres URL nazywamy „witryną”. Wszystkie adresy URL z tym samym schematem, nazwą hosta i portem są uznawane za część witryny i są częścią 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 on jednak tych adresów URL:

  • http://www.google.com/ (niewłaściwy schemat)
  • https://google.com/ (nazwa hosta się nie zgadza)
  • WYMAGANY https://www.google.com:444/ (port nie pasuje)