Introduzione
Questa pagina descrive come utilizzare l'API Service Control v2 per l'ammissione per i servizi gestiti integrati con Service Infrastructure. È destinato ai producer di servizi che vogliono integrare profondamente i propri servizi con Google Cloud.
Service Infrastructure è una piattaforma di base che gli sviluppatori possono usare per produrre, gestire, in modo sicuro 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 di Google e Le API Google Cloud usano questo modello, poiché sono anche basato sull'Service Infrastructure.
Quando un client accede a un servizio, tutte le entità coinvolte nell'accesso tipicamente richiedono un controllo dello stato e delle norme, inclusi consumer, servizio, producer, utente, applicazione, rete e risorse. Con Infrastruttura di servizio, questo processo è chiamato controllo di ammissione, che include autenticazione, autorizzazione, controllo, limitazione di frequenza e altro ancora.
API Service Control v2
La versione 2 dell'API Service Control fornisce un semplice metodo
services.check
che offre il controllo dell'accesso a tutti i servizi integrati con Service Infrastructure.
Questo metodo consente di effettuare le seguenti operazioni in un'unica chiamata di metodo:
- Controllo dello stato
- Stato abuso
- Stato fatturazione
- Stato del consumatore
- Stato del servizio
- Abilitazione del servizio
- Autenticazione
- Token di accesso OAuth di Google
- JWT firmato con l'account di servizio Google
- Autorizzazione
- Controllo
- Audit log di Cloud. L'audit log è associato al servizio "externalaudit.googleapis.com".
Quando un servizio chiama l'API Service Control, il producer è anche
un consumer dell'API Service Control. Pertanto, il metodo services.check
esegue anche il controllo di ammissione sulla chiamata all'API Service Control.
Per fare in modo che un servizio chiami l'API Service Control, devi abilitare l'API Service Control sul progetto producer e le autorizzazioni appropriate per il servizio. Per ulteriori informazioni, consulta la guida introduttiva alle API Cloud e il Controllo degli accessi di Service Control.
Attributi della richiesta
Quando un client accede a un servizio, quest'ultimo deve astrarre l'accesso. in una o più richieste API, che possono essere verificate con il controllo di ammissione. Nella maggior parte dei casi, questi accessi sono vere e proprie richieste API. In altri casi, l'accesso può essere complicato da job di importazione dati o query SQL, e il servizio deve modellare l'accesso in termini di un set di API virtuali richieste ed eseguire il controllo di ammissione su ciascuna richiesta.
Per eseguire il controllo di ammissione utilizzando l'API Service Control, il servizio deve chiamare il metodo services.check con gli attributi della richiesta richiesti. La
nella seguente tabella sono elencati gli attributi necessari per il controllo di ammissione.
Per la specifica completa, consulta
AttributeContext
| Attributo | Descrizione | Esempio |
|---|---|---|
origin.ip |
L'indirizzo IP dell'utente che chiama. | "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 dell'API. | "v1" |
api.protocol |
Il nome del protocollo 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. | "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" |
request.headers |
Le intestazioni della richiesta HTTP. Le intestazioni richieste sono "authorization", "user-agent", "origin", "referer". | |
resource.name |
Il nome della risorsa di destinazione. | "projects/123/topics/news-feed" |
Attributi risorsa
Quando un client accede a un servizio, l'accesso può coinvolgere una o più risorse all'interno del servizio, come la lettura di un oggetto o la creazione di un'istanza VM. Il servizio può utilizzare il controllo di ammissione dell'Service Infrastructure per il controllo dell'accesso su supportate da IAM e Audit log di Cloud. Se il tuo servizio non richiede il controllo dell'accesso, puoi saltare questa sezione.
Per il controllo dell'accesso, un servizio deve passare gli attributi di risorse
services.check insieme agli attributi della richiesta.
La tabella seguente mostra gli attributi delle risorse richiesti per il controllo dell'accesso.
| Attributo | Descrizione | Esempio |
|---|---|---|
name |
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 della risorsa. Il formato è "{service}/{kinds}.{verb}". | "endpointsapis.appspot.com/instances.get" |
Per prestazioni ed efficienza, il metodo services.check consente di controllare più autorizzazioni su una singola risorsa in un'unica chiamata.
Eseguire il controllo di ammissione
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.check per il servizio di cui è stato eseguito il deployment. Dovresti
chiama services.check per eseguire il controllo di ammissione ogni volta che
riceve una richiesta dal servizio.
Per eseguire rapidamente esperimenti sul controllo dell'accesso, puoi utilizzare il comando gcurl
per chiamare il metodo services.check. Consulta:
Introduzione all'API Service Control
per i passaggi di configurazione iniziali.
L'esempio seguente mostra come utilizzare il comando gcurl per chiamare
services.check su 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 del metodo services.check indica se il controllo di ammissione è andato a buon fine. Se viene superato, la risposta deve essere vuota. Se non riesce,
status nella risposta contiene informazioni sull'errore che il servizio
deve restituire al client. Spesso il servizio deve tradurre le informazioni sull'errore nel proprio formato. Il servizio può anche utilizzare le informazioni
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. Tali librerie offrono un'ottima usabilità e gestire automaticamente funzionalità comuni, come l'autenticazione. Per ulteriori informazioni, vedi Spiegazione delle librerie client.