Package google.digitalassetlinks.v1

Índice

Extratos

Esse serviço de API atende a "declarações", que são os veículos usados pelos proprietários para publicar informações sobre os próprios links. A API pode ser usada para recuperar instruções de maneira simples e segura, sem a necessidade de adquirir as instruções diretamente das fontes.

Todas as declarações retornadas por essa API foram feitas em nome dos recursos digitais (por exemplo, sites ou apps Android). 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 desses relacionamentos é 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 origem que correspondem ao destino e à string da instrução especificados.

A API garante que todas as instruções com recursos de origem seguros, como sites HTTPS ou apps Android, tenham sido feitas de forma segura pelo proprietário desses recursos, conforme descrito na especificação técnica do design de recursos digitais. 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 formas com que dois recursos estão relacionados ou enumerar todas as relações de um recurso de origem específico. Exemplo: um recurso que ajuda os usuários a navegar até itens relacionados. Quando um app para dispositivos móveis é executado em um dispositivo, o recurso facilita a navegação até o site ou o perfil do Google+ correspondente.

Recurso do app Android

Descreve um recurso de app Android.

Nome do campo Tipo Descrição
package_name string Os recursos do 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á uma 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 forma exclusiva.

Algumas chaves de assinatura do app são alternadas. Portanto, é possível que elas sejam assinadas por chaves diferentes ao longo do tempo. Eles são tratados como recursos diferentes, já que usamos (nome do pacote, certificado) como o ID exclusivo. Isso normalmente não traz problemas, porque as duas versões do app fazem declarações iguais ou semelhantes. No entanto, outros recursos que fazem declarações sobre o app precisam ser atualizados quando a chave é rotacionada.

As sintaxes para publicar e consultar instruções contêm açúcar sintático para permitir que você especifique facilmente apps conhecidos por vários certificados. REQUIRED

Informações do certificado

Descreve um certificado X509.

Nome do campo Tipo Descrição
sha256_fingerprint string

Impressão digital SHA-265 em letras maiúsculas do certificado. O certificado PEM pode ser adquirido da seguinte maneira:

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

$ 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 seria 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 maiúsculas de cada octeto separadas por dois-pontos).

Recurso

Identifica um recurso de forma exclusiva.

Um recurso 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, apps Android, feeds do Twitter e páginas do Google+.

Nome do campo Tipo Descrição
Campo de união, apenas uma das seguintes opções:
web WebAsset Defina se este é um recurso da Web.
android_app AndroidAppAsset Defina se este é um recurso de 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 A fonte que hospeda a lista de instruções. Isso é usado para encaminhar a chamada Check() para a origem correta.
relation string

String de consulta da relação.

Identificamos relações com strings no formato <kind>/<detail>, em que <kind> precisa ser um conjunto de categorias de objetivos pré-definidas, e <detail> é uma string alfanumérica em formato livre que descreve o caso de uso específico da instrução.

Consulte a documentação da API para ver 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 de recurso precisam corresponder exatamente.

Exemplo: uma consulta com a 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

A 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 especificada na solicitação. REQUIRED
max_age Duration A partir do momento da veiculação, quanto tempo a resposta deve ser considerada válida, com exceção das atualizações. REQUIRED
debug_string string

Mensagem legível que contém 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.

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

Solicitação de lista

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

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

Use somente associações que correspondam à relação especificada.

Consulte a mensagem Statement para ver 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:

  • as strings de relação da consulta e da instrução corresponderem exatamente ou
  • a string de relação da consulta está vazia ou ausente.

Exemplo: uma consulta com a 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, quanto tempo a resposta deve ser considerada válida, com exceção das atualizações. REQUIRED
debug_string string

Mensagem legível que contém 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.

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

Instrução

Descreve uma declaração confiável sobre a relação entre os recursos de origem e 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 local.

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

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

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

Identificamos relações com strings no formato <kind>/<detail>, em que <kind> precisa ser um conjunto de categorias de objetivos pré-definidas, e <detail> é uma string alfanumérica em formato livre que descreve o caso de uso específico da instrução.

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

Exemplo: delegate_permission/common.handle_all_urls OBRIGATÓRIO
target Asset Cada instrução tem um recurso de destino. REQUIRED

Recurso da Web

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 apenas o esquema, o nome do host e as partes da porta. O formato é

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

Os nomes do host precisam ser totalmente qualificados: precisam terminar em um único ponto (".").

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

Os números de porta são fornecidos como um número decimal 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/

No entanto, ele não contém os seguintes 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