Package google.digitalassetlinks.v1

Indice

Istruzioni

Questo servizio API pubblica "istruzioni", ovvero i veicoli utilizzati dai proprietari delle risorse per pubblicare informazioni sui loro link delle risorse. L'API può essere utilizzata per recuperare le istruzioni in modo semplice e sicuro, senza bisogno di acquisirle direttamente dalle origini.

Tutte le dichiarazioni restituite da questa API sono state effettuate per conto di risorse digitali (ad esempio, siti web o app per Android) su altre risorse digitali. Ogni istruzione contiene un asset di origine, un asset di destinazione e una o più relazioni.

La relazione descrive la relazione tra i due asset come rivendicato dalla risorsa di origine. Un esempio di tali relazioni è la delega dei privilegi o delle autorizzazioni.

Elenco

rpc List(ListRequest) returns (ListResponse)

Recupera un elenco di tutte le istruzioni da una determinata origine che corrispondono alla destinazione e alla stringa di istruzione specificate.

L'API garantisce che tutte le dichiarazioni con asset di origine sicuri, ad esempio siti web HTTPS o app per Android, siano state eseguite in modo sicuro dal proprietario delle risorse, come descritto nella specifica di progettazione tecnica dei link di asset digitali. Nello specifico, tieni presente che per i siti web non sicuri (ovvero dove l'URL inizia con http:// anziché con https://) non è possibile garantire questa garanzia.

Il comando List è particolarmente utile nei casi in cui il client API voglia conoscere tutti i modi in cui due asset sono correlati o enumerare tutte le relazioni di una determinata risorsa di origine. Esempio: una funzionalità che consente agli utenti di navigare tra gli elementi correlati. Quando un'app per dispositivi mobili è in esecuzione su un dispositivo, la funzione consente di passare facilmente al sito web o al profilo Google+ corrispondente.

Asset Android

Descrive un asset per app Android.

Nome campo Tipo Descrizione
package_name string Gli asset per app Android sono identificati in modo naturale dal nome del pacchetto Java. Ad esempio, l'app Google Maps utilizza il nome pacchetto com.google.android.apps.maps. OBBLIGATORIA
certificate CertificateInfo

Poiché non esiste un'applicazione globale dell'unicità del nome del pacchetto, richiediamo anche un certificato di firma, che in combinazione con il nome del pacchetto identifica in modo univoco un'app.

Alcune chiavi di firma di alcune app vengono ruotate, quindi nel tempo potrebbero essere firmate da chiavi diverse. Le consideriamo come risorse distinte, in quanto utilizziamo (nome del pacchetto, certificato) come ID univoco. Generalmente, questo non dovrebbe creare problemi perché entrambe le versioni dell'app presentano dichiarazioni uguali o simili. Tuttavia, gli altri asset relativi all'app dovranno essere aggiornati quando una chiave viene ruotata.

Tieni presente che le sintassi per la pubblicazione e l'esecuzione di query di istruzioni contengono zucchero sintattico per consentirti di specificare facilmente le app note da più certificati. OBBLIGATORIA

Informazioni certificato

Descrive un certificato X509.

Nome campo Tipo Descrizione
sha256_fingerprint string

L'impronta SHA-265 maiuscola del certificato. Dal certificato PEM, può essere acquisito così:

$ 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

o in questo modo:

$ 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

In questo esempio, il contenuto di questo campo è 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.

Se questi strumenti non sono disponibili, puoi convertire il certificato PEM nel formato DER, calcolare l'hash SHA-256 di quella stringa e rappresentare il risultato come stringa esadecimale, ovvero rappresentazioni esadecimali maiuscole di ogni ottetto, separate da due punti.

Asset

Identifica in modo univoco una risorsa.

Una risorsa digitale è una persona giuridica online identificabile e indirizzabile che in genere fornisce determinati servizi o contenuti. Esempi di asset sono i siti web, le app per Android, i feed di Twitter e le pagine Plus.

Nome campo Tipo Descrizione
di esempio, solo uno dei seguenti:
web WebAsset Impostalo se si tratta di un asset web.
android_app AndroidAppAsset Impostalo se si tratta di un asset per app per Android.

CheckRequest

Messaggio utilizzato per verificare l'esistenza di un link di asset specifico.

Nome campo Tipo Descrizione
source Asset La sorgente che ospita l'elenco di istruzioni. Questo viene utilizzato per indirizzare la chiamata Check() alla sorgente corretta.
relation string

Stringa di query per la relazione.

Identifichiamo le relazioni con stringhe nel formato <kind>/<detail>, dove <kind> deve far parte di un insieme di categorie di scopi predefinite e <detail> è una stringa alfanumerica minuscola in formato libero che descrive il caso d'uso specifico della dichiarazione.

Consulta la nostra documentazione API per l'elenco aggiornato delle relazioni supportate.

Affinché una query corrisponda a un link all'asset, sia le stringhe di relazione della query sia il link dell'asset devono corrispondere esattamente.

Esempio: una query con relazione delegate_permission/common.handle_all_urls corrisponde a un link dell'asset con relazione delegate_permission/common.handle_all_urls.
target Asset L'asset di destinazione dell'istruzione.

CheckResponse

Messaggio di risposta per la chiamata CheckAssetLinks.

Nome campo Tipo Descrizione
linked bool Impostato su vero se gli asset specificati nella richiesta sono collegati dalla relazione specificata nella richiesta. OBBLIGATORIA
max_age Duration Dal momento della pubblicazione, il periodo di tempo per cui la risposta deve essere considerata valida al netto di ulteriori aggiornamenti. OBBLIGATORIA
debug_string string

Messaggio leggibile contenente informazioni che aiutano gli utenti finali a comprendere, riprodurre ed eseguire il debug del risultato.

Il messaggio è in inglese e al momento non prevediamo di fornire traduzioni.

Tieni presente che non viene fatta alcuna garanzia sui contenuti o sul formato di questa stringa. Qualsiasi suo aspetto può essere soggetto a modifiche senza preavviso. Non tentare di analizzare questi dati a livello di programmazione. Se ritieni di averne bisogno perché le informazioni di cui hai bisogno non sono mostrate in altro modo dall'API, contattaci.

ListList

Messaggio utilizzato per richiedere tutte le dichiarazioni note che hanno un'origine e una relazione specificate.

Nome campo Tipo Descrizione
source Asset La sorgente che ospita l'elenco di istruzioni. Questo viene utilizzato per indirizzare la richiesta List() alla sorgente giusta. OBBLIGATORIA
relation string

Utilizza solo associazioni che corrispondono alla relazione specificata.

Per una definizione dettagliata delle stringhe di relazione, consulta il messaggio Statement.

Affinché una query corrisponda a un'istruzione, deve essere vera una delle seguenti condizioni:

  • Le stringhe di relazione della query e dell'istruzione corrispondono esattamente oppure
  • la stringa di relazione della query è vuota o mancante.

Esempio: una query con relazione delegate_permission/common.handle_all_urls corrisponde a un link dell'asset con relazione delegate_permission/common.handle_all_urls.

Elenco risposte

Messaggio di risposta per la chiamata Elenco.

Nome campo Tipo Descrizione
statements Statement Un elenco di tutte le istruzioni corrispondenti trovate.
max_age Duration Dal momento della pubblicazione, il periodo di tempo per cui la risposta deve essere considerata valida al netto di ulteriori aggiornamenti. OBBLIGATORIA
debug_string string

Messaggio leggibile contenente informazioni che aiutano gli utenti finali a comprendere, riprodurre ed eseguire il debug del risultato.

Il messaggio è in inglese e al momento non prevediamo di fornire traduzioni.

Tieni presente che non viene fatta alcuna garanzia sui contenuti o sul formato di questa stringa. Qualsiasi suo aspetto può essere soggetto a modifiche senza preavviso. Non tentare di analizzare questi dati a livello di programmazione. Se ritieni di averne bisogno perché le informazioni di cui hai bisogno non sono mostrate in altro modo dall'API, contattaci.

Affermazione

Descrive una dichiarazione affidabile sulla relazione tra un asset di origine e un asset di destinazione.

Le istruzioni sono sempre fatte dall'asset di origine, direttamente o delegando a un elenco di istruzioni memorizzato altrove.

Per una definizione più dettagliata di istruzioni e risorse, consulta la pagina di destinazione della documentazione dell'API.

Nome campo Tipo Descrizione
source Asset Ogni istruzione ha un asset di origine. OBBLIGATORIA
relation string

La relazione identifica l'uso dell'istruzione come previsto dal proprietario della risorsa sorgente (ovvero la persona o l'entità che ha emesso la dichiarazione). Ogni dichiarazione completa ha una relazione.

Identifichiamo le relazioni con stringhe nel formato <kind>/<detail>, dove <kind> deve far parte di un insieme di categorie di scopi predefinite e <detail> è una stringa alfanumerica minuscola in formato libero che descrive il caso d'uso specifico della dichiarazione.

Consulta la nostra documentazione API per l'elenco aggiornato delle relazioni supportate.

Esempio: delegate_permission/common.handle_all_urls OBBLIGATORIO
target Asset Ogni istruzione ha un asset di destinazione. OBBLIGATORIA

Asset web

Descrive una risorsa web.

Nome campo Tipo Descrizione
site string

Gli asset web sono identificati da un URL che contiene solo le parti schema, nome host e porta. Il formato è

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

I nomi host devono essere completi e devono terminare con un singolo periodo (".").

Al momento sono consentiti solo gli schemi "http" e "https".

I numeri di porta sono indicati come numeri decimali e devono essere omessi se vengono utilizzati i numeri di porta standard: 80 per http e 443 per https.

Questo URL limitato viene chiamato "sito". Tutti gli URL che condividono lo stesso schema, nome host e porta vengono considerati parte del sito e appartengono quindi all'asset web.

Esempio: l'asset con il sito https://www.google.com contiene tutti questi 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/

Tuttavia, non contiene i seguenti URL:

  • http://www.google.com/ (schema errato)
  • https://google.com/ (il nome host non corrisponde)
  • https://www.google.com:444/ (porta non corrispondente) OBBLIGATORIO