Rapporti di telemetria

Alpha

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Introduzione

Questa pagina descrive come utilizzare l'API Service Control v2 per i report di telemetria per i servizi gestiti integrati con Service Infrastructure. È destinata ai producer di servizi che vogliono integrare profondamente i propri servizi con Google Cloud.

Service Infrastructure è una piattaforma fondamentale che consente agli sviluppatori di produrre, gestire, proteggere e utilizzare API e servizi. che utilizza un semplice modello di utilizzo generico dei servizi: un consumer consuma un servizio gestito da un producer. Tutte le API di Google e le API Google Cloud utilizzano questo modello, poiché sono basate sull'Service Infrastructure.

Quando un consumer accede a un servizio, il servizio invia i dati di telemetria pertinenti alla piattaforma, in modo che sia il consumer che il producer possano osservare l'accesso. Con l'infrastruttura di servizi, questo processo è chiamato reporting sulla telemetria, che include analisi, auditing, fatturazione, logging e monitoraggio.

Nota: per la terminologia utilizzata in questa pagina, consulta il Glossario delle API.

API Service Control v2

L'API Service Control v2 fornisce un metodo services.report semplice che fornisce report sulla telemetria a tutti i servizi integrati con Service Infrastructure. Questo metodo ti consente di eseguire le seguenti operazioni in una chiamata a metodo singolo:

• Analisi
• Controllo
• Fatturazione
• Logging
• Monitoraggio

Quando un servizio segnala i dati di telemetria all'API Service Control, i dati vengono distribuiti al consumer, al producer o a entrambi, a seconda della configurazione del servizio. Per ulteriori informazioni sulla configurazione della telemetria, consulta le sezioni su logging e monitoraggio di google.api.Service.

Affinché un servizio chiami l'API Service Control, il producer deve abilitare l'API Service Control nel progetto del producer e il chiamante deve disporre delle autorizzazioni appropriate sul servizio. Per ulteriori informazioni, consulta la Guida introduttiva alle API Cloud e Controllo dell'accesso all'API Service Control.

Attributi della richiesta

Quando un client accede a un servizio, quest'ultimo deve modellare l'accesso in termini di un insieme di richieste API e descrivere ogni richiesta utilizzando un elemento AttributeContext.

Per generare report sulle metriche API utilizzando l'API Service Control, il servizio deve chiamare il metodo services.report per ogni richiesta con i seguenti attributi. L'API Service Control genererà le metriche API e le invierà a Cloud Monitoring.

Attributo	Descrizione	Esempio
origin.ip	L'indirizzo IP del chiamante.	"1.2.3.4"
api.service	Il nome del servizio API.	"endpointsapis.appspot.com"
api.operation	Il nome del metodo API.	"google.example.hello.v1.HelloService.GetHello"
api.version	La stringa della versione API.	"v1"
api.protocol	Il nome del protocollo dell'API.	"https"
request.id	Un ID richiesta univoco.	"123e4567-e89b-12d3-a456-426655440000"
request.time	Il timestamp della richiesta.	"2019-07-31T05:20:00Z"
request.method	Il nome del metodo HTTP.	"PUBBLICA"
request.scheme	Lo schema dell'URL.	"https"
request.host	L'intestazione dell'host HTTP.	"endpointsapis.appspot.com"
request.path	Il percorso dell'URL.	"/v1/ciao"
response.code	Il codice di stato della risposta.	200
response.size	Le dimensioni della risposta in byte.	100
response.time	Il timestamp della risposta.	"2019-07-31T05:20:02Z"
response.backend_latency	La latenza del backend.	"0,007 s"

Esecuzione di report sulla telemetria

Dopo aver eseguito il deployment della configurazione del servizio nell'API Service Management e dopo che il servizio è pronto per gestire le richieste dei client, puoi iniziare a chiamare services.report per il servizio di cui hai eseguito il deployment. Devi chiamare services.report per eseguire i report sulla telemetria dopo che il servizio riceve una richiesta.

Per sperimentare rapidamente i report sulla telemetria, puoi utilizzare il comando gcurl per chiamare il metodo services.report. Per i passaggi di configurazione iniziali, consulta la guida introduttiva all'API Service Control.

L'esempio seguente mostra come utilizzare il comando gcurl per chiamare services.report tramite 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

In caso di esito positivo, la risposta del metodo services.report deve essere vuota. Se non viene superato, l'errore API deve contenere informazioni dettagliate sull'errore. Per ulteriori informazioni sulla gestione degli errori, consulta Guida alla progettazione delle API > Errori.

Per i servizi di produzione, devi utilizzare una delle librerie client fornite da Google per chiamare l'API Service Control. Queste librerie offrono un'ottima usabilità e gestiscono automaticamente funzionalità comuni come l'autenticazione. Per ulteriori informazioni, consulta la sezione Spiegazione sulle librerie client.