Package google.digitalassetlinks.v1

Índice

Instruções

Esse serviço de API disponibiliza "declarações", que são os veículos usados pelos proprietários de recursos para publicar informações sobre os links deles. A API pode ser usada para recuperar instruções de maneira simples e segura, sem a necessidade de adquiri-las diretamente das fontes.

Todas as declarações retornadas por essa API foram feitas em nome de ativos digitais (por exemplo, sites ou apps Android) sobre outros ativos digitais. Cada instrução contém um recurso de origem, um recurso de destino e uma ou mais relações.

A relação descreve a relação entre os dois recursos conforme reivindicado pelo recurso de origem. Um exemplo dessas relações é a delegação de privilégios ou permissões.

Lista

rpc List(ListRequest) returns (ListResponse)

Recupera uma lista de todas as instruções de uma determinada fonte que corresponde ao destino e à string de instrução especificados.

A API garante que todas as declarações com recursos de origem seguros, como sites HTTPS ou apps Android, sejam feitas de maneira segura pelo proprietário desses recursos, conforme descrito na especificação do design técnico do Digital Asset Links. Especificamente, considere que, para sites não seguros (ou seja, em que o URL começa com http:// em vez de https://), essa garantia não pode ser feita.

O comando List é mais útil nos casos em que o cliente da API quer saber todas as maneiras como dois recursos estão relacionados ou enumerar todas as relações de um determinado recurso de origem. Exemplo: um recurso que ajuda os usuários a navegar para itens relacionados. Quando um aplicativo móvel está sendo executado em um dispositivo, o recurso facilitaria a navegação para o site ou perfil do Google+ correspondente.

AndroidAppAsset

Descreve um recurso de link para app Android.

Nome do campo Tipo Descrição
package_name string Os recursos de link para app Android são naturalmente identificados pelo nome do pacote Java. Por exemplo, o app Google Maps usa o nome de pacote com.google.android.apps.maps. REQUIRED
certificate CertificateInfo

Como não há aplicação global da exclusividade do nome do pacote, também exigimos um certificado de assinatura que, em combinação com o nome do pacote, identifique um app de maneira exclusiva.

As chaves de assinatura de alguns apps são alternadas. Por isso, elas podem ser assinadas por chaves diferentes ao longo do tempo. Tratamos esses itens como recursos distintos, já que usamos (nome do pacote, certificado) como o ID exclusivo. Normalmente, isso não deve causar problemas, já que as duas versões do app vão fazer declarações iguais ou semelhantes. No entanto, outros recursos que fizerem declarações sobre o app vão precisar ser atualizados quando uma chave for rotacionada.

As sintaxes para publicação e consulta de instruções contêm facilidade sintática para permitir facilmente a especificação de apps conhecidos por vários certificados. REQUIRED

CertificateInfo

Descreve um certificado X509.

Nome do campo Tipo Descrição
sha256_fingerprint string

Impressão digital SHA-265 em maiúsculas do certificado. No certificado PEM, ele pode ser adquirido assim:

$ 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 assim:

$ 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

Neste exemplo, o conteúdo desse 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 essas ferramentas não estiverem disponíveis para você, converta o certificado PEM no formato DER, calcule o hash SHA-256 dessa string e represente o resultado como uma string hexadecimal (ou seja, representações hexadecimais em maiúsculas de cada octeto, separadas por dois pontos).

Recurso

Identifica um recurso de forma exclusiva.

Um ativo digital é uma entidade on-line identificável e endereçável que normalmente oferece algum serviço ou conteúdo. Exemplos de recursos são sites, aplicativos Android, feeds do Twitter e páginas do Google+.

Nome do campo Tipo Descrição
campo "Union", apenas um dos seguintes:
web WebAsset Defina se este é um recurso da Web.
android_app AndroidAppAsset Defina se este for um recurso de link para app Android.

CheckRequest

Mensagem usada para verificar a existência de um link de recurso específico.

Nome do campo Tipo Descrição
source Asset Fonte que hospeda a lista de instruções. Isso é usado para rotear a chamada Check() para a origem adequada.
relation string

String de consulta da relação.

Identificamos relações com strings do formato <kind>/<detail>, em que <kind> precisa ser um de um conjunto de categorias de finalidade predefinidas, e <detail> é uma string alfanumérica em letras minúsculas de formato livre que descreve o caso de uso específico da instrução.

Consulte a documentação da API para a lista atual de relações compatíveis.

Para que uma consulta corresponda a um link de recurso, as strings de relação da consulta e do link do recurso devem corresponder exatamente.

Exemplo: uma consulta com relação delegate_permission/common.handle_all_urls corresponde a um link de recurso com a relação delegate_permission/common.handle_all_urls.
target Asset O recurso de destino da instrução.

CheckResponse

Mensagem de resposta para a chamada de CheckAssetLinks.

Nome do campo Tipo Descrição
linked bool Defina como verdadeiro se os recursos especificados na solicitação estiverem vinculados pela relação definida nela. REQUIRED
max_age Duration A partir do momento da veiculação, o tempo de espera da resposta deve ser considerada válida, exceto no caso de futuras atualizações. REQUIRED
debug_string string

Mensagem legível por humanos contendo informações destinadas a ajudar os usuários finais a entender, reproduzir e depurar o resultado.

A mensagem será em inglês e não planejamos oferecer traduções no momento.

Nenhuma garantia é feita em relação ao conteúdo ou formato dessa string. Qualquer aspecto dele pode estar sujeito a alterações sem aviso prévio. Não tente analisar esses dados de forma programática. Se você acha que precisa fazer isso porque as informações necessárias não estão sendo expostas pela API, entre em contato primeiro.

ListRequest

Mensagem usada para solicitar todas as instruções conhecidas que têm uma fonte e uma relação especificadas.

Nome do campo Tipo Descrição
source Asset Fonte que hospeda a lista de instruções. É usado para direcionar a solicitação List() para a origem correta. REQUIRED
relation string

Usa apenas associações que correspondam à relação especificada.

Consulte a mensagem Statement para uma definição detalhada das strings de relação.

Para que uma consulta corresponda a uma instrução, uma das seguintes condições precisa ser verdadeira:

  • se as strings de relação da consulta e da instrução são exatamente iguais, ou
  • se a string de relação da consulta estiver vazia ou ausente.

Exemplo: uma consulta com relação delegate_permission/common.handle_all_urls corresponde a um link de recurso com a relação delegate_permission/common.handle_all_urls.

ListResponse

Mensagem de resposta para a chamada de List.

Nome do campo Tipo Descrição
statements Statement Uma lista de todas as instruções correspondentes que foram encontradas.
max_age Duration A partir do momento da veiculação, o tempo de espera da resposta deve ser considerada válida, exceto no caso de futuras atualizações. REQUIRED
debug_string string

Mensagem legível por humanos contendo informações destinadas a ajudar os usuários finais a entender, reproduzir e depurar o resultado.

A mensagem será em inglês e não planejamos oferecer traduções no momento.

Nenhuma garantia é feita em relação ao conteúdo ou formato dessa string. Qualquer aspecto dele pode estar sujeito a alterações sem aviso prévio. Não tente analisar esses dados de forma programática. Se você acha que precisa fazer isso porque as informações necessárias não estão sendo expostas pela API, entre em contato primeiro.

Instrução

Descreve uma declaração confiável feita sobre a relação entre um recurso de origem e um recurso de destino.

As instruções são sempre feitas pelo recurso de origem, seja diretamente ou delegando a uma lista de instruções armazenada em outro lugar.

Para definições mais detalhadas de declarações e recursos, consulte a página de destino da documentação da API.

Nome do campo Tipo Descrição
source Asset Toda instrução tem um recurso de origem. REQUIRED
relation string

A relação identifica o uso da instrução conforme pretendido pelo proprietário do recurso de origem (ou seja, a pessoa ou entidade que emitiu a declaração). Toda instrução completa tem uma relação.

Identificamos relações com strings do formato <kind>/<detail>, em que <kind> precisa ser um de um conjunto de categorias de finalidade predefinidas, e <detail> é uma string alfanumérica em letras minúsculas de formato livre que descreve o caso de uso específico da instrução.

Consulte a documentação da API para a lista atual de relações compatíveis.

Exemplo: delegate_permission/common.handle_all_urls REQUIRED
target Asset Toda instrução tem um recurso de destino. REQUIRED

WebAsset

Descreve um recurso da Web.

Nome do campo Tipo Descrição
site string

Os recursos da Web são identificados por um URL que contém somente o esquema, o nome do host e as partes da porta. O formato é

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

Os nomes de host precisam estar totalmente qualificados e terminar em um único ponto (".").

Apenas os esquemas "http" e "https" são permitidos no momento.

Os números de porta são fornecidos como decimais e precisam ser omitidos se os números de porta padrão forem usados: 80 para http e 443 para https.

Chamamos esse URL limitado de "site". Todos os URLs que compartilham o mesmo esquema, nome do host e porta são considerados parte do site e, portanto, pertencem ao recurso da Web.

Exemplo: o recurso com o site https://www.google.com contém todos estes URLs:

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

Mas ele não contém estes URLs:

  • http://www.google.com/ (esquema incorreto)
  • https://google.com/ (o nome do host não corresponde)
  • https://www.google.com:444/ (a porta não corresponde) OBRIGATÓRIO