Introduzione
Questa pagina descrive come utilizzare l'API Service Control v2 per il controllo di ammissione 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 client accede a un servizio, tutte le entità coinvolte nell'accesso richiedono in genere un controllo dello stato e dei criteri, inclusi consumer, servizio, producer, utente, applicazione, rete e risorse. Con l'Service Infrastructure, questo processo è chiamato controllo di ammissione, che include autenticazione, autorizzazione, auditing, limitazione di frequenza e altro ancora.
API Service Control v2
L'API Service Control v2 fornisce un metodo services.check semplice che fornisce il controllo di ammissione a tutti i servizi integrati con Service Infrastructure.
Questo metodo ti consente di eseguire le seguenti operazioni in una chiamata a metodo singolo:
- Controllo dello stato
- Stato comportamento illecito
- Stato fatturazione
- Stato del consumatore
- Stato del servizio
- Abilitazione del servizio
- Autenticazione
- Token di accesso Google OAuth
- JWT firmato con l'account di servizio Google
- Autorizzazione
- Controllo
- Audit log di Cloud. Il log di controllo è associato al servizio "externalaudit.googleapis.com".
Quando un servizio chiama l'API Service Control, il producer è anche un
consumer dell'API Service Control. Di conseguenza, il metodo services.check esegue anche il controllo di ammissione sulla chiamata all'API Service Control.
Affinché un servizio chiami l'API Service Control, devi abilitare l'API Service Control nel progetto producer e disporre delle autorizzazioni appropriate per il servizio. Per ulteriori informazioni, consulta la Guida introduttiva alle API Cloud e il Controllo accesso per Service Control.
Attributi della richiesta
Quando un client accede a un servizio, quest'ultimo deve astrarre l'accesso a una o più richieste API che possono essere verificate con il controllo di ammissione. Nella maggior parte dei casi, tali accessi sono effettivamente richieste API reali. In altri casi, l'accesso può essere dovuto a complicati job di importazione dati o query SQL e il servizio deve modellare l'accesso in termini di un insieme di richieste API virtuali ed eseguire il controllo di ammissione su ogni richiesta.
Per eseguire il controllo di ammissione utilizzando l'API Service Control, il servizio deve chiamare il metodo services.check con gli attributi di richiesta obbligatori. La
tabella riportata di seguito elenca gli attributi necessari per il controllo di ammissione.
Per la specifica completa, consulta
AttributeContext.
| Attibuto | 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 |
L'ora 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" |
request.headers |
Le intestazioni delle richieste HTTP. Le intestazioni obbligatorie sono "permission", "user-agent", "origin", "referer". | |
resource.name |
Il nome della risorsa di destinazione. | "projects/123/topics/news-feed" |
Attributi della risorsa
Quando un client accede a un servizio, l'accesso può coinvolgere una o più risorse al suo interno, ad esempio la lettura di un oggetto o la creazione di un'istanza VM. Il servizio può utilizzare il controllo di ammissione di Service Infrastructure per controllo dell'accesso alle risorse, supportato da IAM e Cloud Audit Logs. Se il servizio non ha bisogno del controllo dell'accesso, puoi saltare questa sezione.
Per controllo dell'accesso, un servizio deve passare gli attributi delle risorse al metodo services.check insieme agli attributi della richiesta.
La tabella seguente mostra gli attributi delle risorse richiesti per controllo dell'accesso.
| Attibuto | Descrizione | Esempio |
|---|---|---|
name |
Il nome della risorsa. | "projects/123/locations/global/instances/instance-1" |
type |
Il tipo di risorsa. Il formato è "{service}/{Kind}". | "endpointsapis.appspot.com/Instance" |
permission |
L'autorizzazione per la risorsa. Il formato è "{service}/{kinds}.{verb}". | "endpointsapis.appspot.com/instances.get" |
Per migliorare le prestazioni e l'efficienza, il metodo services.check consente di controllare più autorizzazioni su una singola risorsa in una sola chiamata.
Controllo di ammissione in corso...
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.check per il servizio di cui hai eseguito il deployment. Devi
chiamare services.check per eseguire il controllo di ammissione ogni volta che il
servizio riceve una richiesta.
Per sperimentare rapidamente il controllo di ammissione, puoi usare il comando gcurl
per chiamare il metodo services.check. 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.check tramite HTTP.
gcurl -d '{
"service_config_id": "latest",
"attributes": {
"origin": {
"ip": "1.2.3.4"
},
"api": {
"service": "endpointsapis.appspot.com",
"operation", "google.example.hello.v1.HelloService.GetHello",
"version": "v1",
"protocol": "https"
}
},
"request": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"time": "2019-07-31T05:20:00Z",
"scheme": "https",
"host": "endpointsapis.appspot.com"
"headers": {
"authorization": "Bearer xxx",
"user-agent": "curl/1.0"
}
},
"resources": [
]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:check
{
}
La risposta dal metodo services.check indica se il controllo di ammissione è stato superato. Se passa, la risposta deve essere vuota. Se l'errore status nella risposta non va a buon fine, il servizio deve restituire informazioni sull'errore al client. Spesso il servizio deve tradurre le informazioni
sull'errore nel proprio formato. Il servizio può usare le informazioni
anche per scopi di logging e monitoraggio.
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.