Relatórios de telemetria

Alfa

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Introdução

Esta página descreve como usar a API Service Control v2 para relatórios de telemetria para serviços geridos que estão integrados com a infraestrutura de serviços. Destina-se a produtores de serviços que queiram integrar profundamente os respetivos serviços com o Google Cloud.

A Service Infrastructure é uma plataforma fundamental para os programadores produzirem, gerirem, protegerem e consumirem APIs e serviços. Usa um modelo de utilização de serviços simples e genérico: um consumidor consome um serviço gerido por um produtor. Todas as APIs Google e as APIs Google Cloud usam este modelo, uma vez que também são criadas com base na infraestrutura de serviços.

Quando um consumidor acede a um serviço, o serviço comunica dados de telemetria relevantes à plataforma, para que o consumidor e o produtor possam observar o acesso. Com a infraestrutura de serviços, este processo é denominado relatórios de telemetria, que incluem estatísticas, auditoria, faturação, registo e monitorização.

Nota: para a terminologia usada nesta página, consulte o glossário de APIs.

API Service Control v2

A API Service Control v2 oferece um método simples services.report que fornece relatórios de telemetria a todos os serviços integrados com a infraestrutura de serviços. Este método permite-lhe fazer o seguinte numa única chamada de método:

• Google Analytics
• Auditorias
• Faturação
• Registo
• Monitorização

Quando um serviço comunica dados de telemetria à API Service Control, os dados são distribuídos ao consumidor, ao produtor ou a ambos, consoante a configuração do serviço. Para mais informações sobre a configuração da telemetria, consulte as secções de registo e monitorização de google.api.Service.

Para que um serviço chame a API Service Control, o produtor tem de ativar a API Service Control no projeto do produtor e o autor da chamada tem de ter as autorizações adequadas no serviço. Para mais informações, consulte os artigos Introdução às APIs Cloud e Controlo de acesso da API Service Control.

Atributos de pedido

Quando um cliente acede a um serviço, o serviço tem de modelar o acesso em termos de um conjunto de pedidos de API e descrever cada pedido através de um AttributeContext.

Para comunicar métricas da API através da API Service Control, o serviço tem de chamar o método services.report para cada pedido com os seguintes atributos. A API Service Control gera as métricas da API e envia-as para o Cloud Monitoring.

Atributo	Descrição	Exemplo
origin.ip	O endereço IP do autor da chamada.	"1.2.3.4"
api.service	O nome do serviço da API.	"endpointsapis.appspot.com"
api.operation	O nome do método da API.	"google.example.hello.v1.HelloService.GetHello"
api.version	A string da versão da API.	"v1"
api.protocol	O nome do protocolo da API.	"https"
request.id	Um ID do pedido exclusivo.	"123e4567-e89b-12d3-a456-426655440000"
request.time	A data/hora do pedido.	"2019-07-31T05:20:00Z"
request.method	O nome do método HTTP.	"POST"
request.scheme	O esquema de URL.	"https"
request.host	O cabeçalho do anfitrião HTTP.	"endpointsapis.appspot.com"
request.path	O caminho de URL.	"/v1/hello"
response.code	O código de estado da resposta.	200
response.size	O tamanho da resposta em bytes.	100
response.time	A data/hora da resposta.	"2019-07-31T05:20:02Z"
response.backend_latency	A latência do back-end.	"0,007 s"

Realizar relatórios de telemetria

Depois de implementar a configuração do serviço na API Service Management e o serviço estiver pronto para processar pedidos de clientes, pode começar a chamar services.report para o serviço implementado. Deve chamar services.report para fazer relatórios de telemetria depois de o seu serviço receber um pedido.

Para experimentar rapidamente os relatórios de telemetria, pode usar o comando gcurl para chamar o método services.report. Consulte o artigo Introdução à API Service Control para ver os passos de configuração iniciais.

O exemplo seguinte mostra como usar o comando gcurl para chamar services.report através de HTTP.

gcurl -d '{
  "service_config_id": "latest",
  "operations": [{
    "origin": {
      "ip": "1.2.3.4"
    },
    "api": {
      "service": "endpointsapis.appspot.com",
      "operation", "google.example.endpointsapis.v1.Workspaces.GetWorkspace",
      "version": "v1",
      "protocol": "https"
    },
    "request": {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "size": 50,
      "time": "2019-07-31T05:20:00Z",
    },
    "response": {
      "size": 100,
      "code": 200,
      "time": "2019-07-31T05:20:02Z",
      "backend_latency": "0.007s"
    },
    "destination": {
      "region_code": "us-central1"
    }
    "resource": {
      "name": "projects/123/locations/us-central1/workspaces/default"
    }
  }]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:report

Se for bem-sucedido, a resposta do método services.report deve estar vazia. Se falhar, o erro da API deve conter informações detalhadas sobre o erro. Para mais informações sobre o processamento de erros, consulte o guia de design de APIs > erros.

Para serviços de produção, deve usar uma das bibliotecas cliente fornecidas pela Google para chamar a API Service Control. Estas bibliotecas oferecem uma excelente usabilidade e processam automaticamente a funcionalidade comum, como a autenticação. Para mais informações, consulte o artigo Bibliotecas de cliente explicadas.