Introduzione
Questa pagina descrive come utilizzare l'API Service Control v2 per i report di telemetria per i servizi gestiti integrati con Service Infrastructure. È destinato ai produttori di servizi che vogliono integrare in modo approfondito i propri servizi con Google Cloud.
Service Infrastructure è una piattaforma fondamentale per gli sviluppatori per produrre, gestire, proteggere 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 di Google e le API Google Cloud utilizzano questo modello, poiché sono anche basate su Service Infrastructure.
Quando un consumatore accede a un servizio, quest'ultimo invia alla piattaforma dati di telemetria pertinenti, in modo che sia il consumatore che il producer possano osservare l'accesso. Con Service Infrastructure, questo processo è chiamato report di telemetria, che include analisi, audit, fatturazione, logging e monitoraggio.
API Service Control v2
L'API Service Control v2 fornisce un metodo semplice
services.report
che fornisce report di telemetria a tutti i servizi integrati con
Service Infrastructure. Questo metodo ti consente di eseguire le seguenti operazioni in una singola chiamata al metodo:
- Analytics
- Controllo
- Fatturazione
- Logging
- Monitoraggio
Quando un servizio invia dati di telemetria all'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 possa chiamare l'API Service Control, il producer deve abilitare l'API Service Control nel progetto del producer e il chiamante deve disporre delle autorizzazioni appropriate per il servizio. Per ulteriori informazioni, consulta Guida introduttiva alle API Cloud e Controllo dell'accesso all'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 ogni richiesta utilizzando un
AttributeContext.
Per segnalare le 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 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 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 |
Latenza di backend. | "0,007 s" |
Esecuzione dei report sulla telemetria
Dopo aver eseguito il deployment della configurazione del servizio nell'API Service Management e il servizio è pronto a 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 la generazione di report di telemetria dopo che il tuo
servizio riceve una richiesta.
Per sperimentare rapidamente la generazione di report di telemetria, puoi utilizzare il comando gcurl
per chiamare il metodo services.report. Per i passaggi di configurazione iniziali, consulta Introduzione 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. In caso di errore, l'errore API deve contenere informazioni dettagliate.
Per ulteriori informazioni sulla gestione degli errori, consulta
Guida alla progettazione di 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 una grande usabilità e gestiscono automaticamente le funzionalità comuni, come l'autenticazione. Per saperne di più, vedi Spiegazione delle librerie client.