Decoratori

I decoratori di Cloud Endpoints Frameworks per Python descrivono la configurazione dell'API, metodi, parametri e altri dettagli essenziali 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 quanto segue:

• Creazione dell'API
• Creazione di un'API implementata con più classi

Definizione dell'API (@endpoints.api)

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

limit_definitions

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

• Installa la versione 2.4.5 o successive della libreria 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.

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:

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, un token OAuth2 viene emesso per un ID client specifico, il che significa che questo ID client può essere utilizzato per limitare l'accesso alle tue API. Quando registri le applicazioni per Android nella console Google Cloud, crei un ID client per ciascuna. Questo ID client è quello che richiede un token OAuth2 a Google a scopo di autenticazione. Quando l'API di backend è protetta dall'autenticazione, un token di accesso OAuth2 viene inviato e aperto da Endpoints Frameworks per App Engine, l'ID client viene estratto dal token e poi l'ID viene confrontato con l'elenco di ID client accettabili dichiarati dal backend (l'elenco allowed_client_ids).

L'elenco allowed_client_ids deve essere costituito da tutti gli ID cliente 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 compilazione dell'API. Se specifichi un elenco vuoto, nessun client può accedere all'API.

Tieni presente che in ogni metodo dell'API in cui vuoi verificare l'autenticazione corretta, devi chiamare endpoints.get_current_user(). Per ulteriori informazioni, consulta la sezione Autenticazione degli utenti.

Se utilizzi l'argomento allowed_client_ids e vuoi testare le chiamate autenticate alla tua API utilizzando Explorer API, devi fornire l'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 e esegui il deployment dell'API, quest'ultima è ancora rilevabile 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 clienti, 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 della console Google Cloud, viene creato e denominato automaticamente un ID client predefinito per l'utilizzo da parte del progetto. Quando carichi la tua API di backend in App Engine, viene utilizzato questo ID client. Si tratta dell'ID client web indicato in auth dell'API.

Emittente del token di autenticazione di terze parti

Se la tua applicazione accetta token di autenticazione che non sono token ID Google e 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 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, puoi specificare le classi Message di richiesta e risposta da utilizzare.

Gli argomenti disponibili sono elencati nella tabella seguente:

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

Se la richiesta contiene argomenti di percorso o stringa di query, non puoi utilizzare una semplice classe Message 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 il corpo della richiesta non contiene argomenti, non è necessario definire una classe Message: 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 che hai definito 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 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 ResourceContainer ha un argomento obbligatorio, una richiesta del client deve includerlo in una stringa di query (ad es. yourApi?times=2) o nel percorso dell'URL (ad es. yourApi/2). Tuttavia, affinché l'API riceva un valore dell'argomento utilizzando il percorso dell'URL, devi aggiungere anche il nome dell'argomento al percorso dell'API, come mostrato per l'argomento {times} in path='yourApi/{times}.

Passaggi successivi

• Creazione dell'API
• Creazione di un'API implementata con più classi