Decoratori

I decoratori di Cloud Endpoints Frameworks per Python descrivono la configurazione, i metodi, i parametri e altri dettagli importanti dell'API che definiscono le proprietà e il comportamento dell'endpoint.

Questa pagina descrive in dettaglio i decoratori disponibili. Per informazioni sull'utilizzo dei decoratori per creare l'API, consulta:

Definizione dell'API (@endpoints.api)

Puoi fornire diversi argomenti a @endpoints.api per definire l'API. La seguente tabella descrive gli argomenti disponibili:

Argomenti di @endpoints.api Descrizione Esempio
allowed_client_ids Obbligatorio se l'API utilizza l'autenticazione. Elenco degli ID client per i client autorizzati a richiedere i 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 l'API richiede l'autenticazione e se supporta i client Android. Per i token ID Google, può trattarsi di un elenco di ID client per conto dei quali vengono richiesti i token. Se i token vengono emessi da provider di autenticazione di terze parti, come Auth0, deve essere un dizionario che esegue il mapping dai nomi degli emittenti di autenticazione agli elenchi di segmenti di pubblico. Per saperne di più, consulta ID client e segmenti di pubblico consentiti. audiences=['1-web-apps.apps.googleusercontent.com'] or 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 anche modificare la sezione handlers nel file app.yaml. Consulta 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 i nomi nella libreria client; l'API di backend continua a utilizzare il valore specificato nella proprietà name.

Ad esempio, se la proprietà name dell'API è impostata su dfaanalytics, puoi utilizzare questa proprietà per specificare un nome canonico di DFA Group Analytics; le classi client generate conterranno quindi il nome DfaGroupAnalytics.

Includi gli spazi pertinenti tra i nomi come mostrato; questi vengono sostituiti dalla notazione camel case o dai trattini bassi appropriati.		 canonical_name='DFA Analytics'
description Una breve descrizione dell'API. Questa viene esposta nel servizio di rilevamento per descrivere l'API e, facoltativamente, può essere utilizzata anche per generare la documentazione come descritto in Generare 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. Questo viene visualizzato nella sezione "Scopri di più" di Explorer API nella parte superiore della pagina di Explorer API per consentire agli utenti di scoprire di più sul tuo servizio. documentation='http://link_to/docs'
hostname Il nome host dell'applicazione App Engine. Lo strumento a riga di comando di Endpoints Frameworks utilizza il valore specificato qui quando genera un documento di rilevamento o un documento OpenAPI. Se non specifichi il nome host qui, devi specificarlo nel campo application del file app.yaml o specificare l'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 che esegue il mapping dai nomi degli 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 i percorsi dell'API. Il valore name:
  • Deve iniziare con una lettera minuscola.
  • Deve corrispondere all'espressione regolare [a-z]+[A-Za-z0-9]; ovvero, il resto del nome può essere composto da lettere maiuscole e minuscole o numeri.
Per eseguire il deployment di più API come parte di un singolo servizio, tutti i nomi delle API devono corrispondere all'espressione regolare [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' or name='yourapi'
limit_definitions Facoltativo. Utilizzato per definire le quote per l'API. Per saperne di più, 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 fornito. Il valore predefinito è 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 definire ulteriormente l'ambito del "pacchetto" a cui appartiene questa API, con valori separati da / che specificano i raggruppamenti logici delle API.

Ad esempio, se specifichi cloud/platform, il percorso della libreria client viene impostato su cloud/platform/<ApiName> e il pacchetto della libreria client viene impostato su cloud.plaform.<ApiName>.		 package_path='cloud/platform'
scopes Se non viene fornito, il valore predefinito è l'ambito email (https://www.googleapis.com/auth/userinfo.email), che è obbligatorio per OAuth. Se vuoi, puoi eseguire l'override di questo valore per specificare più ambiti OAuth 2.0. Puoi anche eseguire l'override degli ambiti specificati qui per un determinato metodo API specificando ambiti diversi nel decoratore @endpoints.method. Tuttavia, se definisci più di un ambito, tieni presente che il controllo dell'ambito viene superato se il token viene generato per uno qualsiasi degli ambiti specificati. Per richiedere più ambiti, specifica una singola stringa con uno spazio tra ogni ambito. 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 chiamata echo con la 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 per i tuoi client. Tuttavia, se aggiorni l'API echo alla versione 3.0.0 (perché stai eseguendo il deployment di una modifica che causa interruzioni), il percorso viene modificato in /echo/v3. version='v1' or version='2.1.0'

limit_definitions

Per definire le quote per l'API, specifica l'argomento facoltativo limit_definitions per @endpoints.api. Per configurare una quota, devi anche:

  • Installare la versione 2.4.5 o successive della libreria Endpoints Frameworks.
  • Aggiungere l'argomento metric_costs al decoratore del metodo per ogni metodo a cui vuoi applicare una quota.

Consulta Configurare le quote per tutti i passaggi necessari per configurare una quota.

Specifica 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 Descrizione
nome Il nome del contatore delle richieste API. In genere, si tratta del 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 Endpoints > Servizi. Questo testo viene visualizzato anche per i consumer dell' API nella pagina Quote di IAM e amministrazione e API e Servizi. Il nome visualizzato deve contenere al massimo 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 consumer dell'API, ti consigliamo di utilizzare quanto segue per il nome visualizzato:

  • Utilizza "Richieste" se hai una sola metrica.
  • Se hai più metriche, ognuna deve descrivere il tipo di richiesta e contenere la parola "richieste" (ad esempio, "Richieste di lettura" o "Richieste di scrittura").
  • Utilizza "Unità di quota" anziché "Richieste" se uno dei costi per questa quota è maggiore di 1.

limite Un valore intero che rappresenta il 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 client e segmenti di pubblico consentiti

Per l'autenticazione OAuth2, viene emesso un token OAuth2 per un ID client specifico, il che significa che questo ID client può essere utilizzato per limitare l'accesso alle API. Quando registri le applicazioni Android nella Google Cloud console, crei un ID client per l'applicazione. Questo ID client è quello che richiede un token OAuth2 a Google per l'autenticazione. Quando l'API di backend è protetta dall'autenticazione, viene inviato e aperto un token di accesso OAuth2 da Endpoints Frameworks per App Engine, l'ID client viene estratto dal token e quindi l'ID viene confrontato con l'elenco degli ID client accettabili dichiarati dal backend (l'elenco allowed_client_ids).

L'elenco allowed_client_ids deve essere composto da tutti gli ID client che hai ottenuto tramite la Google Cloud console 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 può accedere all'API.

Tieni presente che in ogni metodo API in cui vuoi verificare la corretta autenticazione, devi chiamare endpoints.get_current_user(). Per saperne di più, consulta Autenticare gli utenti.

Se utilizzi l'argomento allowed_client_ids e vuoi testare le chiamate autenticate all'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 e accessibile pubblicamente in Explorer API.

Informazioni sui segmenti di pubblico

L'elenco allowed_client_ids protegge l'API di backend dai client non autorizzati. Tuttavia, è necessaria un'ulteriore protezione per proteggere i client, in modo che il 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 Google Cloud console, viene creato automaticamente un ID client predefinito e denominato per l'utilizzo da parte del progetto. Quando carichi l'API di backend in App Engine, questa utilizza l'ID client. Si tratta dell'ID client web menzionato nell'autenticazione API .

Emittente del token di autenticazione di terze parti

Se la tua applicazione accetta token di autenticazione che non sono token ID Google e vengono 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 impostare le impostazioni audiences, scopes e allowed_client_ids per l'intera API utilizzando @endpoints.api o per un metodo utilizzando @endpoints.method. Se queste impostazioni sono specificate sia a livello di API sia 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:

Argomenti di @endpoints.method 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. Si tratta di un dizionario con le seguenti coppie chiave-valore:
  • name: un nome specificato nell'argomento limit_definitions del decoratore API.
  • cost: un numero intero che specifica il costo per ogni richiesta. Il costo consente ai metodi di consumare a velocità diverse dalla stessa quota. Ad esempio, se una quota ha un limite di 1000 e un costo di 1, l'applicazione chiamante può effettuare 1000 richieste al minuto prima di superare il limite. Con un costo di 2 per la stessa quota, un'applicazione chiamante può effettuare solo 500 richieste al minuto prima di superare il limite.
 metric_costs={'read-requests': 1}
http_method Il metodo HTTP da utilizzare. Se non lo imposti, per impostazione predefinita viene utilizzato 'POST'. 'GET'
name Un nome alternativo per questo metodo. Il valore name:
  • Deve iniziare con una lettera minuscola.
  • Deve corrispondere all'espressione regolare [a-z]+[A-Za-z0-9]*.
 'yourApi'
path Il percorso URI per accedere a questo metodo. Se non lo imposti, 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 Google Protocol RPC Request Message da utilizzare nella chiamata al metodo. In alternativa, puoi fornire il nome della classe. YourRequestClass
Classe Response Message La classe Google Protocol RPC Response Message da utilizzare nella chiamata al metodo. In alternativa, puoi fornire il nome della classe. YourResponseClass

Utilizzo di ResourceContainer per gli argomenti del percorso o della stringa di query

Se la richiesta contiene argomenti del percorso o della stringa di query, non puoi utilizzare una semplice Message classe come descritto in Creare l'API. Devi invece utilizzare una classe ResourceContainer, come segue:

  1. Definisci una classe Message che contenga tutti gli argomenti passati nel corpo della richiesta. Se non sono presenti argomenti nel corpo della richiesta, non devi definire una Message classe: utilizza semplicemente message_types.VoidMessage.) Ad esempio:

    class Greeting(messages.Message):
    """Greeting that stores a message."""

    message = messages.StringField(1)

  2. Definisci un ResourceContainer con la classe Message definita nel passaggio precedente come primo parametro. Specifica gli argomenti del percorso e della stringa di query nei parametri successivi. Ad esempio:

    MULTIPLY_RESOURCE = endpoints.ResourceContainer(
    Greeting,
    times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),

    dove il primo argomento è la classe Message per i dati nel corpo della richiesta e times è un numero previsto nel percorso o nella stringa di query che accompagna la richiesta.

  3. Fornisci il ResourceContainer al metodo che gestisce la richiesta, nel primo parametro sostituendo la classe Message della richiesta che altrimenti verrebbe fornita in quella posizione. Questo snippet mostra sia ResourceContainer sia endpoints.method:

    # This ResourceContainer is similar to the one used for get_greeting, but
# this one also contains a request body in the form of a Greeting message.
MULTIPLY_RESOURCE = endpoints.ResourceContainer(
    Greeting,
    times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),
)

@endpoints.method(
    # This method accepts a request body containing a Greeting message
    # and a URL parameter specifying how many times to multiply the
    # message.
    MULTIPLY_RESOURCE,
    # This method returns a Greeting message.
    Greeting,
    path="greetings/multiply/{times}",
    http_method="POST",
    name="greetings.multiply",
)
def multiply_greeting(self, request):
    return Greeting(message=request.message * request.times)

  4. Aggiungi il parametro path come mostrato, per includere l'API.

  5. Se il tuo ResourceContainer ha un argomento obbligatorio, una richiesta client deve includerlo in una stringa di query (ad esempio, yourApi?times=2) o nel percorso URL (ad esempio, yourApi/2). Tuttavia, affinché l'API riceva un valore dell'argomento utilizzando il percorso URL, devi anche aggiungere il nome dell'argomento al percorso dell'API come mostrato per l'argomento {times} in path='yourApi/{times}.

Passaggi successivi