Introduzione
Questa pagina descrive come utilizzare la versione 2 dell'API Service Control per i report sulla 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 dei servizi 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'Service Infrastructure.
Quando un consumatore accede a un servizio, il servizio registra i dati di telemetria pertinenti sulla piattaforma, in modo che sia il consumatore sia 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.
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'Service Infrastructure. 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 possa chiamare l'API Service Control, il producer deve attivare l'API Service Control nel progetto del producer e l'utente chiamante deve 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 ogni richiesta utilizzando un 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 dell'API e le invierà a Cloud Monitoring.
| Attributo | Descrizione | Esempio |
|---|---|---|
origin.ip |
L'indirizzo IP della persona che chiama. | "1.2.3.4" |
api.service |
Il nome del servizio API. | "endpointsapis.appspot.com" |
api.operation |
Il nome del metodo dell'API. | "google.example.hello.v1.HelloService.GetHello" |
api.version |
La stringa della versione dell'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. | "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 |
La latenza del backend. | "0,007 s" |
Eseguire i report sulla telemetria
Dopo aver eseguito il deployment della configurazione del servizio nell'API Service Management e aver verificato che il servizio sia pronto a soddisfare le richieste dei clienti, puoi iniziare a chiamare services.report per il servizio di cui è stato eseguito il deployment. Devi chiamare services.report per eseguire i report sulla telemetria dopo che il tuo servizio ha ricevuto una richiesta.
Per eseguire rapidamente esperimenti con i report sulla telemetria, puoi utilizzare il comando gcurl
per chiamare il metodo services.report. Per i passaggi di configurazione iniziale, 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 dell'API dovrebbe contenere informazioni dettagliate sull'errore.
Per ulteriori informazioni sulla gestione degli errori, consulta la 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, consulta Librerie client spiegate.