Package google.digitalassetlinks.v1

Indice

Dichiarazioni

Questo servizio API pubblica "Dichiarazioni", ovvero i veicoli utilizzati dai proprietari degli asset per pubblicare informazioni sui propri link agli asset. L'API può essere utilizzata per recuperare istruzioni in modo semplice e sicuro, senza la necessità di acquisirle direttamente dalle fonti.

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

La relazione descrive la relazione tra le due risorse rivendicata dalla risorsa di origine. Un esempio di queste relazioni è la delega di privilegi o autorizzazioni.

Elenco

rpc List(ListRequest) returns (ListResponse)

Recupera un elenco di tutte le istruzioni di una determinata origine che corrispondono al target e alla stringa di istruzioni specificati.

L'API garantisce che tutte le dichiarazioni con asset di origine sicuri, ad esempio siti web HTTPS o app per Android, siano state effettuate in modo sicuro dal proprietario di tali asset, come descritto nelle specifiche di progettazione tecnica di Digital Asset Links. In particolare, devi tenere presente che per i siti web non sicuri (ovvero dove l'URL inizia con http:// anziché https://), questa garanzia non può essere fornita.

Il comando List è utile soprattutto nei casi in cui il client API voglia conoscere tutti i modi in cui due asset sono correlati o enumerare tutte le relazioni di un determinato asset di origine. Esempio: una funzionalità che aiuta gli utenti a raggiungere elementi correlati. Quando un'app mobile è in esecuzione su un dispositivo, la funzione semplifica l'accesso al sito web o al profilo Google+ corrispondente.

AndroidAppAsset

Descrive un asset per app per Android.

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

Poiché non è prevista un'applicazione globale dell'univocità dei nomi dei pacchetti, è necessario anche un certificato di firma, che, in combinazione con il nome del pacchetto, identifica in modo univoco un'app.

Le chiavi di firma di alcune app vengono ruotate, quindi nel tempo potrebbero essere firmate da chiavi diverse. Vengono considerati risorse distinte, in quanto utilizziamo (nome del pacchetto, certificato) come ID univoco. Normalmente questo non dovrebbe rappresentare alcun problema, in quanto entrambe le versioni dell'app riporteranno affermazioni uguali o simili. Tuttavia, le altre risorse che fanno dichiarazioni sull'app dovranno essere aggiornate quando una chiave viene ruotata.

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

CertificateInfo

Descrive un certificato X509.

Nome campo Tipo Descrizione
sha256_fingerprint string

L'impronta SHA-265 maiuscola del certificato. Dal certificato PEM, può essere acquisito nel seguente modo:

$ 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 una stringa esadecimale (ovvero, rappresentazioni esadecimali maiuscole di ogni ottetto, separate da due punti).

Asset

Identifica in modo univoco una risorsa.

Un asset digitale è un'entità online identificabile e indirizzabile che in genere fornisce alcuni servizi o contenuti. Esempi di asset sono siti web, app per Android, feed di Twitter e pagine Plus.

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

CheckRequest

Messaggio utilizzato per verificare l'esistenza di un collegamento a uno specifico asset.

Nome campo Tipo Descrizione
source Asset La fonte che ospita l'elenco degli estratti conto. Viene utilizzato per instradare la chiamata Check() all'origine corretta.
relation string

Stringa di query per la relazione.

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

Per l'elenco aggiornato delle relazioni supportate, consulta la documentazione relativa all'API.

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

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

CheckResponse

Messaggio di risposta per la chiamata CheckAssetLinks.

Nome campo Tipo Descrizione
linked bool Viene impostato su true se gli asset specificati nella richiesta sono collegati dalla relazione specificata nella richiesta. REQUIRED
max_age Duration Dalla pubblicazione, indica per quanto tempo la risposta deve essere considerata valida salvo ulteriori aggiornamenti. REQUIRED
debug_string string

Messaggio leggibile contenente informazioni destinate ad aiutare gli utenti finali a comprendere, riprodurre ed eseguire il debug del risultato.

Il messaggio sarà in inglese e al momento non prevediamo di offrire alcuna traduzione.

Tieni presente che non vengono garantite garanzie in merito ai contenuti o al formato di questa stringa. Qualsiasi suo aspetto potrebbe essere soggetto a modifica senza preavviso. Non tentare di analizzare questi dati in modo programmatico. Se ritieni di dover svolgere questa operazione perché le informazioni di cui hai bisogno non vengono altrimenti esposte dall'API, contattaci.

ListRequest

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

Nome campo Tipo Descrizione
source Asset La fonte che ospita l'elenco degli estratti conto. Viene utilizzato per indirizzare la richiesta List() all'origine corretta. REQUIRED
relation string

Utilizza solo le associazioni che corrispondono alla relazione specificata.

Vedi il messaggio Statement per una definizione dettagliata delle stringhe di relazione.

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

  • 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 di asset con la relazione delegate_permission/common.handle_all_urls.

ListResponse

Messaggio di risposta per la chiamata dell'elenco.

Nome campo Tipo Descrizione
statements Statement Un elenco di tutte le istruzioni corrispondenti trovate.
max_age Duration Dalla pubblicazione, indica per quanto tempo la risposta deve essere considerata valida salvo ulteriori aggiornamenti. REQUIRED
debug_string string

Messaggio leggibile contenente informazioni destinate ad aiutare gli utenti finali a comprendere, riprodurre ed eseguire il debug del risultato.

Il messaggio sarà in inglese e al momento non prevediamo di offrire alcuna traduzione.

Tieni presente che non vengono garantite garanzie in merito ai contenuti o al formato di questa stringa. Qualsiasi suo aspetto potrebbe essere soggetto a modifica senza preavviso. Non tentare di analizzare questi dati in modo programmatico. Se ritieni di dover svolgere questa operazione perché le informazioni di cui hai bisogno non vengono altrimenti esposte dall'API, contattaci.

Affermazione

Descrive un'affermazione attendibile relativa alla relazione tra una risorsa di origine e una risorsa target.

Le dichiarazioni vengono sempre effettuate dalla risorsa di origine, direttamente o delegandole a un elenco di dichiarazioni archiviato altrove.

Per definizioni più dettagliate di estratti conto e asset, consulta la pagina di destinazione della documentazione API.

Nome campo Tipo Descrizione
source Asset Ogni istruzione dispone di un asset di origine. REQUIRED
relation string

La relazione identifica l'uso della dichiarazione come previsto dal proprietario della risorsa di origine (ovvero la persona o la persona giuridica che ha emesso la dichiarazione). Ogni affermazione completa ha una relazione.

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

Per l'elenco aggiornato delle relazioni supportate, consulta la documentazione relativa all'API.

Esempio: delegate_permission/common.handle_all_urls OBBLIGATORIO
target Asset Ogni estratto conto ha un asset target. REQUIRED

WebAsset

Descrive un asset 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: devono terminare con un singolo punto (".").

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

I numeri di porta sono forniti 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 sono considerati parte del sito e quindi appartengono all'asset web.

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