Package google.digitalassetlinks.v1

Índice

Resúmenes

Este servicio de API entrega "resúmenes", que son los vehículos que utilizan los propietarios del activo para publicar información acerca de sus vínculos. La API se puede usar para recuperar declaraciones de forma simple y segura, sin necesidad de adquirirlas directamente de las fuentes.

Todas las declaraciones devueltas por esta API se realizaron en nombre de los activos digitales (por ejemplo, sitios web o apps para Android) sobre otros recursos digitales. Cada instrucción contiene un elemento de origen, uno de destino y una o más relaciones.

La relación describe la relación entre los dos activos según lo reclamado por el recurso de origen. Un ejemplo de tales relaciones es la delegación de privilegios o permisos.

Lista

rpc List(ListRequest) returns (ListResponse)

Recupera una lista de todas las declaraciones de una fuente determinada que coinciden con el destino y la string de instrucción especificados.

La API garantiza que el propietario de esos elementos haya realizado de manera segura todas las declaraciones con recursos de origen seguros, como sitios web HTTPS o aplicaciones para Android, como se describe en la especificación de diseño técnico de Vínculos de recursos digitales. Específicamente, debes tener en cuenta que, en el caso de sitios web no seguros (es decir, en los que la URL comienza con http:// en lugar de https://), no se puede realizar esta garantía.

El comando List es más útil en los casos en los que el cliente de la API desea conocer todas las formas en las que se relacionan dos elementos o enumerar todas las relaciones de un recurso de origen particular. Ejemplo: una función que ayuda a los usuarios a navegar a elementos relacionados. Cuando una aplicación móvil se ejecuta en un dispositivo, la función facilita la navegación al sitio web o perfil de Google+ correspondiente.

Recurso de aplicación de Android

Describe un elemento de la app para Android.

Nombre del campo Tipo Descripción
package_name string Los recursos de apps para Android se identifican de forma natural por su nombre de paquete de Java. Por ejemplo, la app de Google Maps utiliza el nombre de paquete com.google.android.apps.maps. REQUIRED
certificate CertificateInfo

Debido a que no hay una aplicación global de la singularidad del nombre del paquete, también solicitamos un certificado de firma, que en combinación con el nombre del paquete identifica de forma exclusiva una aplicación.

Las claves de algunas apps se rotan, por lo que pueden firmarse con diferentes claves en el tiempo. Tratamos estos elementos como elementos independientes, ya que usamos (nombre del paquete, certificado) como el ID único. Esto no debería presentar problemas, ya que ambas versiones de la app realizan las mismas declaraciones o similares. Sin embargo, otros elementos que realizan declaraciones acerca de la aplicación deberán actualizarse cuando se rota una clave.

(Ten en cuenta que las sintaxis para publicar y consultar instrucciones contienen azúcar sintáctico a fin de que puedas especificar con facilidad apps que son conocidas por varios certificados). REQUIRED

Información del certificado

Describe un certificado X509.

Nombre del campo Tipo Descripción
sha256_fingerprint string

La huella digital SHA-265 en mayúsculas del certificado. Desde el certificado PEM, se puede adquirir de la siguiente manera:

$ 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 algo así:

$ 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

En este ejemplo, el contenido de este campo sería 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 estas herramientas no están disponibles, puedes convertir el certificado PEM al formato DER, calcular el hash SHA-256 de esa string y representar el resultado como una string hexadecimal (es decir, representaciones hexadecimales en mayúsculas de cada octeto, separadas por dos puntos).

Recurso

Identifica un elemento de forma única.

Un activo digital es una entidad en línea identificable y direccionable que generalmente proporciona algún servicio o contenido. Algunos ejemplos de activos son sitios web, apps para Android, feeds de Twitter y páginas de Google+.

Nombre del campo Tipo Descripción
Campo de unión, solo una de las siguientes opciones:
web WebAsset Configura si este es un recurso web.
android_app AndroidAppAsset Configura si se trata de un elemento de la app para Android.

CheckRequest

Mensaje utilizado para comprobar la existencia de un vínculo de elemento específico.

Nombre del campo Tipo Descripción
source Asset La fuente que aloja la lista de instrucciones. Se usa para enrutar la llamada Check() a la fuente adecuada.
relation string

Cadena de consulta de la relación

Identificamos relaciones con strings del formato <kind>/<detail>, en el que <kind> debe ser parte de un conjunto de categorías de propósito predefinidas, y <detail> es una string alfanumérica en formato libre en minúscula que describe el caso de uso específico de la declaración.

Consulta nuestra documentación de la API para ver la lista actual de relaciones admitidas.

Para que una consulta coincida con un vínculo de elemento, tanto las strings de relación de la consulta como las del vínculo del elemento deben coincidir exactamente.

Ejemplo: Una consulta con la relación delegate_permission/common.handle_all_urls coincide con un vínculo de elemento con la relación delegate_permission/common.handle_all_urls.
target Asset Es el elemento de destino del resumen.

CheckResponse

Mensaje de respuesta para la llamada CheckAssetLinks.

Nombre del campo Tipo Descripción
linked bool Se establece como verdadero si los elementos especificados en la solicitud están vinculados por la relación especificada en la solicitud. REQUIRED
max_age Duration Desde el momento de la publicación, cuánto tiempo más se debe considerar la respuesta como válida, tras la prohibición de las actualizaciones. REQUIRED
debug_string string

Mensaje legible que incluye información destinada a ayudar a los usuarios finales a comprender, reproducir y depurar el resultado.

El mensaje se mostrará en inglés y, por el momento, no planeamos ofrecer traducciones.

Tenga en cuenta que no se garantiza el contenido ni el formato de esta cadena. Cualquier aspecto puede estar sujeto a cambios sin previo aviso. No debes intentar analizar estos datos de manera programática. Si considera que necesita hacerlo porque la API no expone la información que necesita, comuníquese con nosotros primero.

Solicitud de lista

Mensaje utilizado para solicitar todas las declaraciones conocidas que tengan una relación y una fuente especificadas.

Nombre del campo Tipo Descripción
source Asset La fuente que aloja la lista de instrucciones. Se usa para dirigir la solicitud List() a la fuente correcta. REQUIRED
relation string

Usa solo asociaciones que coincidan con la relación especificada.

Consulta el mensaje Statement para obtener una definición detallada de las strings de relación.

Para que una consulta coincida con una instrucción, se debe cumplir una de las siguientes condiciones:

  • Las strings de relación de la consulta y la declaración coinciden de forma exacta.
  • falta la string de relación de la consulta.

Ejemplo: Una consulta con la relación delegate_permission/common.handle_all_urls coincide con un vínculo de elemento con la relación delegate_permission/common.handle_all_urls.

Respuesta de lista

Mensaje de respuesta para la llamada de lista.

Nombre del campo Tipo Descripción
statements Statement Una lista de todas las declaraciones coincidentes que se encontraron.
max_age Duration Desde el momento de la publicación, cuánto tiempo más se debe considerar la respuesta como válida, tras la prohibición de las actualizaciones. REQUIRED
debug_string string

Mensaje legible que incluye información destinada a ayudar a los usuarios finales a comprender, reproducir y depurar el resultado.

El mensaje se mostrará en inglés y, por el momento, no planeamos ofrecer traducciones.

Tenga en cuenta que no se garantiza el contenido ni el formato de esta cadena. Cualquier aspecto puede estar sujeto a cambios sin previo aviso. No debes intentar analizar estos datos de manera programática. Si considera que necesita hacerlo porque la API no expone la información que necesita, comuníquese con nosotros primero.

Declaración

Describe una declaración confiable que se haya hecho sobre la relación entre un elemento de origen y uno de destino.

Las declaraciones siempre las realiza el activo de origen, ya sea de forma directa o mediante la delegación de una lista de declaraciones que se almacena en otro lugar.

Para obtener definiciones más detalladas de las declaraciones y los recursos, consulte nuestra página de destino de la documentación de la API.

Nombre del campo Tipo Descripción
source Asset Cada instrucción tiene un recurso de origen. REQUIRED
relation string

La relación identifica el uso de la declaración según lo previsto por el propietario del activo de origen (es decir, la persona o entidad que emitió la declaración). Cada instrucción completa tiene una relación.

Identificamos relaciones con strings del formato <kind>/<detail>, en el que <kind> debe ser parte de un conjunto de categorías de propósito predefinidas, y <detail> es una string alfanumérica en formato libre en minúscula que describe el caso de uso específico de la declaración.

Consulta nuestra documentación de la API para ver la lista actual de relaciones admitidas.

Ejemplo: delegate_permission/common.handle_all_urls OBLIGATORIO
target Asset Cada resumen tiene un elemento de destino. REQUIRED

Elemento web

Describe un elemento web.

Nombre del campo Tipo Descripción
site string

Los recursos web se identifican mediante una URL que contiene solo el esquema, el nombre de host y las partes de los puertos. El formato es

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

Los nombres de host deben estar completamente calificados y deben terminar en un solo punto (".").

Solo se permiten los esquemas "http" y "https".

Los números de puerto se proporcionan como número decimal y deben omitirse si se usan los números de puerto estándar: 80 para http y 443 para https.

Esta URL limitada se denomina "sitio". Todas las URL que comparten el mismo esquema, nombre de host y puerto se consideran parte del sitio y, por lo tanto, pertenecen al elemento web.

Ejemplo: El recurso con el sitio https://www.google.com contiene todas estas 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/

Sin embargo, no contiene las siguientes URL:

  • http://www.google.com/ (esquema incorrecto)
  • https://google.com/ (el nombre de host no coincide)
  • https://www.google.com:444/ (el puerto no coincide) OBLIGATORIO