Package google.digitalassetlinks.v1

Index

Relevés

Ce service d'API diffuse des "relevés" qui permettent aux propriétaires d'éléments de publier des informations sur leurs liens d'éléments. L'API peut être utilisée pour récupérer des instructions de manière simple et sécurisée, sans qu'il soit nécessaire de les acquérir directement auprès des sources.

Toutes les déclarations renvoyées par cette API ont été faites au nom d'assets numériques (par exemple, des sites Web ou des applications Android) concernant d'autres assets numériques. Chaque instruction contient un asset source, un asset cible et une ou plusieurs relations.

La relation décrit la relation entre les deux éléments, telle que revendiquée par l'élément source. La délégation de droits ou d'autorisations en est un exemple.

Liste

rpc List(ListRequest) returns (ListResponse)

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

L'API garantit que toutes les instructions comportant des éléments sources sécurisés, comme des sites Web HTTPS ou des applications Android, ont été effectué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. Plus précisément, sachez que pour les sites Web non sécurisés (où l'URL commence par http:// au lieu de https://), cette garantie ne peut pas être effectuée.

La commande List est particulièrement utile lorsque le client API souhaite connaître toutes les relations entre deux éléments, ou énumérer toutes les relations d'un élément source particulier. Exemple: une fonctionnalité qui aide les utilisateurs à accéder aux éléments associés. Lorsqu'une application mobile s'exécute sur un appareil, cette fonctionnalité facilite l'accès au site Web ou au profil Google+ correspondants.

Élément AndroidAppAsset

Décrit un composant Application Android.

Nom du champ Type Description
package_name string Les composants Application Android sont naturellement identifiés 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 aucune mesure d'application globale concernant l'unicité du nom de package, nous avons également besoin d'un certificat de signature, qui, associé au nom du package, permet d'identifier une application de manière unique.

Les clés de signature de certaines applications font l'objet d'une rotation. Par conséquent, elles peuvent être signées par d'autres clés au fil du temps. Nous les traitons comme des éléments distincts, car nous utilisons (nom du package, certificat) comme identifiant unique. Normalement, cela ne pose aucun problème, car les deux versions de l'application émettent des déclarations identiques ou similaires. Toutefois, les autres éléments qui font des déclarations sur l'application devront être mis à jour lors de la rotation d'une clé.

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

Informations sur le certificat

Décrit un certificat X509.

Nom du champ Type Description
sha256_fingerprint string

Empreinte numérique SHA-265 en majuscules du certificat. Le certificat PEM 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 suit:

$ 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 devrait être 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 la forme d'une chaîne hexadécimale (c'est-à-dire des représentations hexadécimales majuscules de chaque octet séparées par des deux-points).

Asset

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

Un asset numérique est une entité en ligne identifiable et adressable qui fournit généralement du service ou du contenu. Les sites Web, les applications Android, les flux Twitter et les pages Google Plus en sont des exemples.

Nom du champ Type Description
Union, un seul des champs suivants:
web WebAsset Indiquez s'il s'agit d'un asset Web.
android_app AndroidAppAsset Indiquez s'il s'agit d'un composant Application Android.

CheckRequest

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

Nom du champ Type Description
source Asset Source hébergeant la liste d'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 les chaînes au format <kind>/<detail>, où <kind> doit faire partie d'un ensemble de catégories d'objectifs prédéfinies, et <detail> est une chaîne alphanumérique à forme libre minuscule décrivant le cas d'utilisation spécifique de l'instruction.

Consultez la documentation de l'API pour obtenir la liste actuelle des relations compatibles.

Pour qu'une requête corresponde à un lien d'élément, les chaînes de relation de la requête et du lien d'é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 Élément cible de l'instruction.

CheckResponse

Message de réponse pour l'appel CheckAssetLinks.

Nom du champ Type Description
linked bool Défini sur "true" si les éléments spécifiés dans la requête sont liés par la relation spécifiée dans la requête. 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 des mises à jour sont effectuées. REQUIRED
debug_string string

Message dans un format lisible 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 le proposer pour le moment.

Notez que nous ne garantissons pas le contenu ni le format de cette chaîne. Tous ses aspects sont susceptibles d'être modifiés sans préavis. N'essayez pas d'analyser ces données par programmation. Si vous pensez que vous devez effectuer cette opération parce que l'API ne fournit pas les informations dont vous avez besoin, veuillez d'abord nous contacter.

Demande de liste

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

Nom du champ Type Description
source Asset Source hébergeant la liste d'instructions. Cela permet de rediriger la requête List() vers la bonne source. REQUIRED
relation string

N'utilisez que des associations correspondant à 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:

  • Les chaînes de relation de la requête et de l'instruction correspondent exactement.
  • 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.

Réponse de liste

Message de réponse pour l'appel de la 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 des mises à jour sont effectuées. REQUIRED
debug_string string

Message dans un format lisible 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 le proposer pour le moment.

Notez que nous ne garantissons pas le contenu ni le format de cette chaîne. Tous ses aspects sont susceptibles d'être modifiés sans préavis. N'essayez pas d'analyser ces données par programmation. Si vous pensez que vous devez effectuer cette opération parce que l'API ne fournit pas les informations dont vous avez besoin, veuillez d'abord nous contacter.

Propos

Décrit une déclaration fiable concernant la relation entre un élément source et un élément cible.

Les déclarations sont toujours faites par l'élément source, soit directement, soit en déléguant l'opération à une liste de relevés stockée ailleurs.

Pour obtenir des définitions plus détaillées des relevés et des éléments, veuillez consulter la page de 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é qui l'a émise). Chaque instruction complète a une relation.

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

Consultez la documentation de l'API pour obtenir la liste actuelle des relations compatibles.

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

Asset Web

Décrit un élément Web.

Nom du champ Type Description
site string

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

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

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

Seuls les schémas "http" et "https" sont actuellement autorisés.

Les numéros de port sont donnés sous forme de nombres décimaux et 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 partageant le même schéma, le même nom d'hôte et le même port sont considérées comme faisant partie du site et appartiennent donc à l'asset Web.

Exemple: L'asset avec le site https://www.google.com contient toutes ces 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/

mais 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