I decoratori Cloud Endpoints per Python descrivono la configurazione dell'API, i metodi, i parametri e altri dettagli essenziali che definiscono le proprietà e il comportamento dell'endpoint.
In questa pagina vengono descritti in dettaglio i decorator disponibili. Per informazioni sull'utilizzo dei decorator per creare la tua API, consulta quanto segue:
Definizione dell'API (@endpoints.api
)
Puoi fornire diversi argomenti a @endpoints.api
per definire l'API. La tabella seguente descrive gli argomenti disponibili:
Argomenti @endpoints.api | Descrizione | Esempio |
---|---|---|
allowed_client_ids |
Obbligatorio se l'API utilizza l'autenticazione. Elenco di ID client per i client autorizzati a richiedere token. Per saperne di più, consulta ID client e segmenti di pubblico consentiti. | allowed_client_ids=['1-web-apps.apps.googleusercontent.com','2-android-apps.apps.googleusercontent.com', endpoints.API_EXPLORER_CLIENT_ID ] |
api_key_required |
Facoltativo. Utilizzato per limitare l'accesso alle richieste che forniscono una chiave API. | api_key_required=True |
audiences |
Obbligatorio se la tua API richiede l'autenticazione e se supporti i client Android. Per i token ID Google, può trattarsi di un elenco di ID client per conto dei quali vengono richiesti. Se i token sono emessi da provider di autenticazione di terze parti, ad esempio Auth0, deve essere un dizionario mappato dai nomi degli emittenti di autenticazione agli elenchi dei segmenti di pubblico. Per saperne di più, consulta ID client e segmenti di pubblico consentiti. | audiences=['1-web-apps.apps.googleusercontent.com'] o audiences={"auth0": ["aud-1.auth0.com", "aud-2.auth0.com"]} |
base_path |
Facoltativo. Utilizzato per pubblicare l'API dal percorso specificato. Se specifichi questo argomento, devi modificare anche la sezione handlers nel file app.yaml . |
Consulta la sezione Pubblicare l'API da un percorso diverso. |
canonical_name |
Facoltativo. Utilizzato per specificare un nome diverso o più leggibile per l'API nella libreria client. Questo nome viene utilizzato per generare nomi nella libreria client; l'API di backend continua a utilizzare il valore specificato nella proprietà name .Ad esempio, se la tua API ha name impostato su dfaanalytics, potresti utilizzare questa proprietà per specificare un nome canonico di DFA Group Analytics; le classi client generate conterranno il nome DfaGroupAnalytics .Devi includere gli spazi pertinenti tra i nomi, come mostrato, e devono essere sostituiti con lettere maiuscole e minuscole appropriate. |
canonical_name='DFA Analytics' |
description |
Una breve descrizione dell'API. Queste vengono mostrate nel servizio di rilevamento per descrivere l'API e, facoltativamente, possono essere utilizzate anche per generare la documentazione come descritto in Generazione di librerie client. | description='Sample API for a simple game' |
documentation |
Facoltativo. L'URL in cui gli utenti possono trovare la documentazione su questa versione dell'API. Questi dati vengono visualizzati nell'evidenziazione "Scopri di più" di Explorer API nella parte superiore della pagina Explorer API per consentire agli utenti di ottenere informazioni sul tuo servizio. | documentation='http://link_to/docs' |
hostname |
Il nome host della tua applicazione App Engine. Lo strumento a riga di comando di Endpoint Frameworks utilizza il valore specificato qui quando genera un documento Discovery o un documento OpenAPI. Se non specifichi il nome host qui, devi specificarlo nel campo application del file app.yaml o specificare il tuo ID progetto quando esegui il deployment dell'applicazione App Engine. |
hostname='your_app_id.appspot.com' |
issuers |
Facoltativo. Le configurazioni personalizzate dell'emittente JWT. Deve essere un dizionario mappato dai nomi delle emittenti agli oggetti endpoints.Issuer . |
issuers={"auth0": endpoints.Issuer("https://test.auth0.com", "https://test.auth0.com/.well-known/jwks.json")} |
name |
obbligatorio. Il nome dell'API, che viene utilizzato come prefisso per tutti i metodi e percorsi dell'API. Il valore name :
[a-z][a-z0-9]{0,39} , ovvero il nome deve iniziare con una lettera minuscola, il resto dei caratteri deve essere composto da lettere minuscole o numeri e la lunghezza massima è di 40 caratteri. |
name='yourApi' o name='yourapi' |
limit_definitions |
Facoltativo. Utilizzato per definire le quote per l'API. Per ulteriori informazioni, consulta limit_definitions. | |
owner_domain |
Facoltativo. Il nome di dominio dell'entità proprietaria dell'API. Utilizzato insieme a owner_name per fornire suggerimenti per assegnare un nome corretto alla libreria client quando viene generata per questa API. Il percorso del pacchetto è l'inverso di owner_domain e package_path , se specificato. L'impostazione predefinita è appid.apppost.com |
owner_domain='your-company.com' |
owner_name |
Facoltativo. Il nome dell'entità proprietaria dell'API. Utilizzato insieme a owner_domain per fornire suggerimenti per assegnare un nome corretto alla libreria client quando viene generata per questa API. |
owner_name='Your-Company' |
package_path |
Facoltativo. Viene utilizzato per ampliare l'ambito Il "pacchetto" a cui appartiene questa API, con valori separati da / specificando raggruppamenti logici di API.Ad esempio, se specifichi cloud/platform risultati nel percorso della libreria client impostato su cloud/platform/<ApiName> e nel pacchetto della libreria client impostato su cloud.plaform.<ApiName> . |
package_path='cloud/platform' |
scopes |
Se non viene specificato, il valore predefinito è l'ambito email (https://www.googleapis.com/auth/userinfo.email ), obbligatorio per OAuth. Se vuoi, puoi eseguire l'override di questa impostazione per specificare più ambiti OAuth 2.0. Puoi anche eseguire l'override degli ambiti specificati qui per un particolare metodo API specificando ambiti diversi nel decorator @endpoints.method . Tuttavia, se definisci più di un ambito, tieni presente che il controllo dell'ambito viene superato se il token è stato creato per uno qualsiasi degli ambiti specificati. Per richiedere più ambiti, specifica una singola stringa con uno spazio tra un ambito e l'altro. |
scopes=['ss0', 'ss1 and_ss2'] |
title |
Facoltativo. Il testo visualizzato in Explorer API come titolo dell'API ed esposto nei servizi di rilevamento e directory. | title='My Backend API' |
version |
obbligatorio. Specifica la versione di Cloud Endpoints. Questo valore viene visualizzato nel percorso dell'API. Se specifichi una stringa di versione compatibile con lo standard SemVer, nel percorso dell'API viene visualizzato solo il numero di versione principale quando esegui il deployment dell'API. Ad esempio, un'API denominata echo con versione 2.1.0 avrà un percorso simile a /echo/v2 . Se aggiorni l'API echo alla versione 2.2.0 ed esegui il deployment di una modifica compatibile con le versioni precedenti, il percorso rimane /echo/v2 . In questo modo puoi aggiornare il numero di versione dell'API quando apporti una modifica compatibile con le versioni precedenti senza interrompere i percorsi esistenti dei tuoi client. Tuttavia, se aggiorni l'API echo alla versione 3.0.0 (perché stai eseguendo il deployment di una modifica che provoca un errore), il percorso viene cambiato in /echo/v3 . |
version='v1' o version='2.1.0' |
limit_definitions
Per definire le quotas per la tua API, devi specificare l'argomento facoltativo limit_definitions
in @endpoints.api
. Per configurare una quota, devi anche:
- Installare la versione 2.4.5 o successiva della libreria di Endpoints Frameworks.
- Aggiungi l'argomento
metric_costs
al decoratore del metodo per ogni metodo a cui vuoi applicare una quota.
Consulta Configurazione delle quote per tutti i passaggi necessari per impostare una quota.
Puoi specificare un elenco di una o più istanze LimitDefinition
, simile al seguente:
quota_limits = [
endpoints.LimitDefinition(
"name",
"Display name",
limit)
]
Ogni istanza LimitDefinition
deve avere i seguenti valori:
Elemento | Description |
---|---|
name | Il nome del contatore delle richieste API. In genere, questo è il tipo di richiesta (ad esempio "richieste di lettura" o "richieste di scrittura") che identifica in modo univoco la quota. |
Nome visualizzato | Il testo visualizzato per identificare la quota nella scheda Quote della pagina Endpoint > Servizi. Questo testo viene mostrato anche ai consumatori della tua API nella pagina Quote di IAM e amministrazione e API e servizi. Il nome visualizzato deve contenere un massimo di 40 caratteri. Per motivi di leggibilità, il testo "al minuto per progetto" viene aggiunto automaticamente al nome visualizzato nelle pagine Quote. Per mantenere la coerenza con i nomi visualizzati dei servizi Google elencati nelle pagine Quote visualizzate dai consumatori della tua API, consigliamo di utilizzare quanto segue per il nome visualizzato:
|
limite | Un valore intero che corrisponde al numero massimo di richieste al minuto per progetto consumer per la quota. |
Esempio
quota_limits = [ endpoints.LimitDefinition('read-requests', 'Read Requests', 1000), endpoints.LimitDefinition('list-requests', 'List Requests', 100), endpoints.LimitDefinition('write-requests', 'Write Requests', 50) ] @endpoints.api(name='bookstore', version='v1', limit_definitions=quota_limits)
ID cliente e segmenti di pubblico consentiti
Per l'autenticazione OAuth2, un token OAuth2 viene inviato a un ID client specifico, il che significa che questo ID client può essere utilizzato per limitare l'accesso alle API.
Quando registri le app per Android nella console
Google Cloud, crei un ID client. Questo ID client è quello che richiede un token OAuth2
a Google per scopi di autenticazione. Quando l'API di backend è protetta tramite autenticazione, un token di accesso OAuth2 viene inviato e aperto da Endpoints Frameworks per App Engine, l'ID client viene estratto dal token e quindi confrontato con l'elenco di ID client accettabili dichiarati del backend (l'elenco allowed_client_ids
).
L'elenco allowed_client_ids
dovrebbe essere composto da tutti gli ID client che hai ottenuto tramite la console Google Cloud per le tue app web, Android e altre app client. Ciò significa che i client devono essere noti
al momento della creazione dell'API. Se specifichi un elenco vuoto, nessun client potrà accedere all'API.
Tieni presente che in ogni metodo API in cui vuoi verificare l'autenticazione corretta
è necessario chiamare endpoints.get_current_user()
.
Per ulteriori informazioni, consulta Autenticazione degli utenti.
Se utilizzi l'argomento allowed_client_ids
e vuoi testare le chiamate autenticate
alla tua API utilizzando Explorer API, devi fornire il relativo ID client
nell'elenco di allowed_client_ids
specificando la costante
endpoints.API_EXPLORER_CLIENT_ID
. Tieni presente che se allowed_client_ids
contiene solo endpoints.API_EXPLORER_CLIENT_ID
ed esegui il deployment dell'API, l'API è comunque rilevabile pubblicamente e accessibile pubblicamente in Explorer API.
Informazioni sui segmenti di pubblico
L'elenco allowed_client_ids
protegge l'API di backend da client non autorizzati. Tuttavia, è necessaria un'ulteriore protezione per proteggere i client, in modo che
il loro token di autenticazione funzioni solo per l'API di backend prevista. Per i client Android, questo meccanismo è l'argomento audiences
, in cui specifichi l'ID client dell'API di backend.
Tieni presente che quando crei un progetto nella console Google Cloud, viene creato automaticamente un ID client predefinito, che viene denominato per essere utilizzato dal progetto. Quando carichi l'API di backend in App Engine, viene utilizzato questo ID client. Si tratta dell'ID client web indicato nell'autenticazione API.
Emittente del token di autenticazione di terze parti
Se la tua applicazione accetta token di autenticazione diversi da quelli ID Google e che sono emessi da emittenti di terze parti, devi impostare correttamente gli argomenti audiences
e issuers
in @endpoints.api
per fornire le informazioni sugli emittenti di terze parti. Ad esempio:
@endpoints.api(
audiences={'auth0': ['aud-1.auth0.com', 'aud-2.auth0.com']},
issuers={'auth0': endpoints.Issuer('https://test.auth0.com',
'https://test.auth0.com/.well-known/jwks.json')})
class GreetingApi(remote.Service):
Definizione di un metodo API (@endpoints.method
)
Puoi configurare le impostazioni audiences
, scopes
e allowed_client_ids
per l'intera API utilizzando @endpoints.api
oppure per un metodo utilizzando
@endpoints.method
. Se queste impostazioni sono specificate sia a livello di API che a livello di metodo, l'impostazione del metodo ha la precedenza.
Per creare un metodo nell'API, decora il metodo Python corrispondente con @endpoints.method
, fornendo gli argomenti per configurare l'utilizzo del metodo. Ad esempio, specifichi le classi Message
di richiesta e risposta da utilizzare.
Gli argomenti disponibili sono elencati nella tabella seguente:
@endpoints.method argomenti |
Descrizione | Esempio |
---|---|---|
allowed_client_ids |
Questa impostazione sostituisce l'attributo equivalente specificato in @endpoints.api . Per saperne di più, consulta ID client e segmenti di pubblico consentiti. |
['1-web-apps.apps.googleusercontent.com', '2-android-apps.apps.googleusercontent.com'] |
api_key_required |
Facoltativo. Utilizzato per limitare l'accesso alle richieste che forniscono una chiave API. | api_key_required=True |
audiences |
Esegue l'override dell'argomento equivalente specificato in @endpoints.api . Per saperne di più, consulta ID client e segmenti di pubblico consentiti. |
['1-web-apps.apps.googleusercontent.com'] |
metric_costs |
Facoltativo. Indica che il metodo ha un limite di quota. Questo è un dizionario con le seguenti coppie chiave-valore:
|
metric_costs={'read-requests': 1} |
http_method |
Il metodo HTTP da utilizzare. Se non imposti questa opzione, per impostazione predefinita viene utilizzato 'POST' . |
'GET' |
name |
Un nome alternativo per questo metodo. Il valore name :
|
'yourApi' |
path |
Il percorso dell'URI per accedere a questo metodo. Se non imposti questa opzione, viene utilizzato il nome del metodo Python. Se prevedi di aggiungere la gestione delle API, non includere una barra finale nel percorso. | 'yourapi/path' |
Classe Request Message |
La classe Request Message del protocollo Google Protocol RPC da utilizzare nella chiamata al metodo. In alternativa, puoi fornire il nome della classe. |
YourRequestClass |
Classe Response Message |
La classe Response Message del protocollo Google Protocol RPC da utilizzare nella chiamata al metodo. In alternativa, puoi fornire il nome della classe. |
YourResponseClass |
Utilizzo di ResourceContainer
per argomenti relativi al percorso o alla stringa di query
Se la richiesta contiene argomenti relativi al percorso o alla stringa di query, non puoi utilizzare una classe Message
semplice, come descritto nella sezione Creare l'API.
Devi invece utilizzare una classe ResourceContainer
, come segue:
Definisci una classe
Message
con tutti gli argomenti passati nel corpo della richiesta. Se il corpo della richiesta non contiene argomenti, non è necessario definire una classeMessage
, ma è sufficiente utilizzaremessage_types.VoidMessage
. Ad esempio:Definisci un valore
ResourceContainer
con la classeMessage
definita nel passaggio precedente come primo parametro. Specifica gli argomenti del percorso e della stringa di query nei parametri successivi. Ad esempio:dove il primo argomento è la classe
Message
per i dati nel corpo della richiesta etimes
è un numero previsto nel percorso o nella stringa di query che accompagna la richiesta.Fornisci
ResourceContainer
al metodo che gestisce la richiesta, nel primo parametro, sostituendo la classeMessage
della richiesta che altrimenti verrebbe fornita in quella località. Questo snippet mostra siaResourceContainer
cheendpoints.method
:Aggiungi il parametro
path
come mostrato per includere l'API.Se
ResourceContainer
ha un argomento richiesto, una richiesta client deve includerlo in una stringa di query (ad esempio,yourApi?times=2
) o nel percorso dell'URL (ad esempio,yourApi/2
). Tuttavia, affinché l'API riceva un valore di argomento utilizzando il percorso dell'URL, devi aggiungere anche il nome dell'argomento al percorso dell'API, come mostrato per l'argomento{times}
inpath='yourApi/{times}
.