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 la telemetria per i servizi gestiti integrati con Service Infrastructure. È destinato ai produttori di servizi che vogliono integrare profondamente i propri servizi con Google Cloud.

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

Quando un consumer accede a un servizio, quest'ultimo segnala i dati di telemetria pertinenti di dati alla piattaforma, in modo che sia il consumatore che il produttore possano osservare l'accesso. Con l'Infrastruttura di servizio, questa procedura è chiamata generazione di report sulla telemetria, che include analisi, controllo, fatturazione, logging e monitoraggio.

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

API Service Control v2

La versione 2 dell'API Service Control fornisce un semplice services.report metodo che genera report sulla telemetria per tutti i servizi integrati con l'Infrastruttura di servizio. Questo metodo consente di eseguire le seguenti operazioni in una singola chiamata al metodo:

• Analytics
• Controllo
• Fatturazione
• Logging
• Monitoraggio

Quando un servizio registra i dati di telemetria nell'API Service Control, i dati vengono distribuiti al consumatore, al produttore o a entrambi, a seconda della configurazione del servizio. Per ulteriori informazioni sulla configurazione della telemetria, consulta le sezioni relative a logging e monitoraggio di google.api.Service.

Affinché un servizio chiami l'API Service Control, il producer deve Abilitare l'API Service Control sul progetto producer e il chiamante devono disporre delle autorizzazioni appropriate per il servizio. Per ulteriori informazioni, consulta Introduzione alle API Cloud e Controllo degli accessi dell'API Service Control.

Attributi della richiesta

Quando un client accede a un servizio, il servizio deve modellare l'accesso in termini di un insieme di richieste API e descrivere ciascuna richiesta utilizzando AttributeContext

Per generare report sulle metriche API utilizzando l'API Service Control, il servizio deve chiamare services.report per ogni richiesta con i seguenti attributi. L'API Service Control genererà le metriche dell'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 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.	"POST"
request.scheme	Lo schema dell'URL.	"https"
request.host	L'intestazione dell'host HTTP.	"endpointsapis.appspot.com"
request.path	Il percorso dell'URL.	"/v1/hello"
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 in Service Management API e il tuo servizio sia pronto a gestire le richieste dei client, puoi inizia 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 tuo servizio ha ricevuto una richiesta.

Per sperimentare rapidamente i report sulla telemetria, puoi utilizzare l'gcurl per richiamare il metodo services.report. Consulta: Introduzione all'API Service Control per i passaggi di configurazione iniziali.

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. In caso di errore, l'errore dell'API dovrebbe contenere informazioni dettagliate sull'errore. Per ulteriori informazioni sulla gestione degli errori, consulta Guida alla progettazione dell'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 le funzionalità comuni, come l'autenticazione. Per ulteriori informazioni, vedi Spiegazione delle librerie client.