Package google.digitalassetlinks.v1

Index

Les déclarations

Ce service d'API diffuse des "instructions", c'est-à-dire les véhicules utilisés par les propriétaires d'éléments pour publier des informations sur leurs liens vers des éléments. L'API peut être utilisée pour récupérer des instructions de manière simple et sécurisée, sans avoir à les acquérir directement auprès des sources.

Toutes les instructions renvoyées par cette API ont été établies pour le compte de ressources numériques (par exemple, des sites Web ou des applications Android) concernant d'autres ressources numériques. Chaque instruction contient un élément source, un élément cible et une ou plusieurs relations.

La relation décrit la relation entre les deux éléments tels qu'ils sont revendiqués par l'élément source. La délégation de privilèges ou d'autorisations est un exemple de ce type de relations.

Liste

rpc List(ListRequest) returns (ListResponse)

Récupère la liste de toutes les instructions d'une source donnée qui correspondent à la cible et à la chaîne d'instruction spécifiées.

L'API garantit que toutes les instructions comportant des éléments sources sécurisés, tels que les sites Web HTTPS ou les applications Android, ont été créées de manière sécurisée par le propriétaire de ces éléments, comme décrit dans les spécifications de conception technique de Digital Asset Links. En particulier, vous devez tenir compte du fait que cette garantie ne peut pas être fournie pour les sites Web non sécurisés (c'est-à-dire, lorsque l'URL commence par http:// au lieu de https://).

La commande List est particulièrement utile lorsque le client API souhaite connaître toutes les manières dont deux éléments sont liés ou énumérer toutes les relations d'un élément source particulier. Exemple: une fonctionnalité qui aide les utilisateurs à naviguer vers des éléments connexes. Lorsqu'une application mobile est exécutée sur un appareil, cette fonctionnalité facilite l'accès au site Web ou au profil Google+ correspondant.

AndroidAppAsset

Décrit un composant Application Android.

Nom du champ Type Description
package_name string Les éléments d'application Android sont identifiés naturellement par leur nom de package Java. Par exemple, l'application Google Maps utilise le nom de package com.google.android.apps.maps. REQUIRED
certificate CertificateInfo

Étant donné qu'il n'existe pas d'application globale de l'unicité du nom du package, nous exigeons également un certificat de signature, qui, en combinaison avec le nom du package, permet d'identifier une application de manière unique.

Les clés de signature de certaines applications sont alternées. Elles peuvent donc être signées avec des clés différentes au fil du temps. Nous les traitons comme des éléments distincts, car nous utilisons (package name, cert) comme identifiant unique. Cela ne devrait normalement pas poser de problème, car les deux versions de l'application feront des déclarations identiques ou similaires. Toutefois, les autres éléments comportant des déclarations concernant l'application devront être mis à jour lors de la rotation d'une clé.

Notez que les syntaxes de publication et d'interrogation d'instructions contiennent du sucre syntaxique pour vous permettre de spécifier facilement des applications connues par plusieurs certificats. REQUIRED

CertificateInfo

Décrit un certificat X509.

Nom du champ Type Description
sha256_fingerprint string

Empreinte SHA-265 en majuscules du certificat. À partir du certificat PEM, il peut être obtenu comme suit:

$ 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

ou comme ceci:

$ 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

Dans cet exemple, le contenu de ce champ est 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.

Si ces outils ne sont pas disponibles, vous pouvez convertir le certificat PEM au format DER, calculer le hachage SHA-256 de cette chaîne et représenter le résultat sous forme de chaîne hexadécimale (c'est-à-dire des représentations hexadécimales en majuscules de chaque octet, séparées par des deux-points).

Élément

Identifie un élément de manière unique.

Un actif numérique est une entité en ligne identifiable et adressable qui fournit généralement des services ou des contenus. Exemples d'éléments : sites Web, applications Android, flux Twitter et pages Google+.

Nom du champ Type Description
Union, l'un des éléments suivants uniquement:
web WebAsset Définissez s'il s'agit d'un élément Web.
android_app AndroidAppAsset Définissez s'il s'agit d'un composant Application Android.

CheckRequest

Message utilisé pour vérifier l'existence d'un lien vers un élément spécifique.

Nom du champ Type Description
source Asset Source hébergeant la liste des instructions. Cela permet d'acheminer l'appel Check() vers la source appropriée.
relation string

Chaîne de requête pour la relation.

Nous identifions les relations avec des chaînes au format <kind>/<detail>, où <kind> doit faire partie d'un ensemble de catégories de finalité prédéfinies, et <detail> est une chaîne alphanumérique minuscule de forme libre qui décrit le cas d'utilisation spécifique de l'instruction.

Reportez-vous à la documentation de l'API pour obtenir la liste actuelle des relations acceptées.

Pour qu'une requête corresponde à un lien d'élément, les chaînes de relation de la requête et du lien de l'élément doivent correspondre exactement.

Exemple: une requête avec la relation delegate_permission/common.handle_all_urls correspond à un lien d'élément avec la relation delegate_permission/common.handle_all_urls.
target Asset Composant cible de l'instruction.

CheckResponse

Message de réponse à l'appel CheckAssetLinks.

Nom du champ Type Description
linked bool Défini sur "true" si les éléments spécifiés dans la demande sont associés par la relation spécifiée dans celle-ci. REQUIRED
max_age Duration À partir de la date de diffusion, délai pendant lequel la réponse doit être considérée comme valide, sauf si d'autres mises à jour sont disponibles. REQUIRED
debug_string string

Message lisible par l'humain contenant des informations destinées à aider les utilisateurs finaux à comprendre, à reproduire et à déboguer le résultat.

Le message sera en anglais et nous ne prévoyons pas de proposer de traduction pour le moment.

Notez qu'aucune garantie n'est faite quant au contenu ou au format de cette chaîne. Tout aspect du contenu est susceptible d'être modifié sans préavis. N'essayez pas d'analyser ces données de manière programmatique. Si vous pensez avoir besoin de le faire parce que les informations dont vous avez besoin ne sont pas divulguées par l'API, veuillez d'abord nous contacter.

ListRequest

Message utilisé pour demander toutes les instructions connues ayant une source et une relation spécifiées.

Nom du champ Type Description
source Asset Source hébergeant la liste des instructions. Cela permet de diriger la requête List() vers la source appropriée. REQUIRED
relation string

Utilisez uniquement les associations qui correspondent à la relation spécifiée.

Consultez le message Statement pour obtenir une définition détaillée des chaînes de relation.

Pour qu'une requête corresponde à une instruction, l'une des conditions suivantes doit être remplie:

  • que les chaînes de relation de la requête et de l'instruction correspondent exactement, ou
  • la chaîne de relation de la requête est vide ou manquante.

Exemple: une requête avec la relation delegate_permission/common.handle_all_urls correspond à un lien d'élément avec la relation delegate_permission/common.handle_all_urls.

ListResponse

Message de réponse à l'appel de liste.

Nom du champ Type Description
statements Statement Liste de toutes les instructions correspondantes trouvées.
max_age Duration À partir de la date de diffusion, délai pendant lequel la réponse doit être considérée comme valide, sauf si d'autres mises à jour sont disponibles. REQUIRED
debug_string string

Message lisible par l'humain contenant des informations destinées à aider les utilisateurs finaux à comprendre, à reproduire et à déboguer le résultat.

Le message sera en anglais et nous ne prévoyons pas de proposer de traduction pour le moment.

Notez qu'aucune garantie n'est faite quant au contenu ou au format de cette chaîne. Tout aspect du contenu est susceptible d'être modifié sans préavis. N'essayez pas d'analyser ces données de manière programmatique. Si vous pensez avoir besoin de le faire parce que les informations dont vous avez besoin ne sont pas divulguées par l'API, veuillez d'abord nous contacter.

Propos

Énoncé fiable concernant la relation entre un élément source et un élément cible.

Les déclarations sont toujours effectuées par l'élément source, soit directement, soit en déléguant l'accès à une liste d'instructions stockée ailleurs.

Pour obtenir une définition plus détaillée des instructions et des éléments, consultez la page de destination de la documentation de l'API.

Nom du champ Type Description
source Asset Chaque instruction est associée à un élément source. REQUIRED
relation string

La relation identifie l'utilisation de la déclaration telle que prévue par le propriétaire de l'élément source (c'est-à-dire la personne ou l'entité ayant émis la déclaration). Chaque énoncé complet a une relation.

Nous identifions les relations avec des chaînes au format <kind>/<detail>, où <kind> doit faire partie d'un ensemble de catégories de finalité prédéfinies, et <detail> est une chaîne alphanumérique minuscule de forme libre qui décrit le cas d'utilisation spécifique de l'instruction.

Reportez-vous à la documentation de l'API pour obtenir la liste actuelle des relations acceptées.

Exemple: delegate_permission/common.handle_all_urls REQUIRED
target Asset Chaque instruction correspond à un élément cible. REQUIRED

WebAsset

Décrit un élément Web.

Nom du champ Type Description
site string

Les éléments Web sont identifiés par une URL qui ne contient que les parties schéma, nom d'hôte et port. Le format est le suivant :

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

Les noms d'hôte doivent être complets: ils doivent se terminer par un seul point (".").

Pour le moment, seuls les schémas "http" et "https" sont autorisés.

Les numéros de ports sont indiqués sous forme de nombre décimal. Ils doivent être omis si les numéros de port standards sont utilisés: 80 pour http et 443 pour https.

Nous appelons cette URL limitée le "site". Toutes les URL qui partagent le même schéma, nom d'hôte et port sont considérées comme faisant partie du site et appartiennent donc à l'élément Web.

Exemple: l'élément avec le site https://www.google.com contient toutes les URL suivantes:

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

Toutefois, il ne contient pas les URL suivantes:

  • http://www.google.com/ (schéma incorrect)
  • https://google.com/ (le nom d'hôte ne correspond pas)
  • https://www.google.com:444/ (le port ne correspond pas) OBLIGATOIRE