Décorateurs

Les décorateurs Cloud Endpoints Frameworks pour Python décrivent la configuration, les méthodes, les paramètres et d'autres informations essentielles de l'API qui définissent les propriétés et le comportement du point de terminaison.

Cette page décrit en détail les décorateurs disponibles. Pour plus d'informations sur comment utiliser des décorateurs pour créer votre API, consultez les articles suivants :

Définir l'API (@endpoints.api)

Vous pouvez fournir plusieurs arguments à @endpoints.api pour définir votre API. Le tableau suivant décrit les arguments disponibles :

Arguments @endpoints.api Description Exemple
allowed_client_ids Requis si votre API utilise l'authentification. Liste des identifiants clients autorisés à demander des jetons. Pour plus d'informations, consultez la section ID clients et audiences autorisés. allowed_client_ids=['1-web-apps.apps.googleusercontent.com','2-android-apps.apps.googleusercontent.com', endpoints.API_EXPLORER_CLIENT_ID]
api_key_required Facultatif. Utilisé pour limiter l'accès aux requêtes fournissant une clé API. api_key_required=True
audiences Obligatoire si votre API requiert une authentification et si vous prenez en charge les clients Android. Pour les jetons d'ID Google, il peut s'agir de la liste des ID clients pour lesquels les jetons sont demandés. Si les jetons sont émis par des fournisseurs d'authentification tiers, tels que Auth0, il doit s'agir d'un dictionnaire mappant des noms d'émetteurs autorisés aux listes d'audiences. Pour plus d'informations, consultez la section ID clients et audiences autorisés. audiences=['1-web-apps.apps.googleusercontent.com'] ou audiences={"auth0": ["aud-1.auth0.com", "aud-2.auth0.com"]}
base_path Facultatif. Utilisé pour diffuser votre API à partir du chemin spécifié. Si vous spécifiez cet argument, vous devez également modifier la section handlers de votre fichier app.yaml. Consultez la section Diffuser votre API depuis un autre chemin d'accès.
canonical_name Facultatif. Utilisé pour spécifier un nom différent ou plus lisible pour l'API dans la bibliothèque cliente. Ce nom est utilisé pour générer les noms dans la bibliothèque cliente. L'API backend continue d'utiliser la valeur spécifiée dans la propriété name.

Par exemple, si la propriété name de votre API est définie sur dfaanalytics, vous pouvez utiliser cette propriété pour spécifier le nom canonique de DFA Group Analytics. Les classes client générées contiennent alors le nom DfaGroupAnalytics.

Vous devez inclure les espaces appropriés entre les noms comme indiqué. Ceux-ci seront complétés par le camel case ou les traits de soulignement appropriés.		 canonical_name='DFA Analytics'
description Brève description de l'API. Elle est présentée dans le service de découverte pour décrire votre API et peut éventuellement aussi être utilisée pour générer de la documentation, comme décrit sur la page Générer des bibliothèques clientes. description='Sample API for a simple game'
documentation Facultatif. URL où les utilisateurs peuvent trouver de la documentation sur cette version de l'API. Elle est utilisée pour le lien "En savoir plus", situé en haut de la page de l'explorateur d'API, pour permettre aux utilisateurs de se familiariser avec votre service. documentation='http://link_to/docs'
hostname Nom d'hôte de votre application App Engine. L'outil de ligne de commande Endpoints Frameworks utilise la valeur que vous spécifiez ici lorsqu'il génère un document Google Discovery ou un document OpenAPI. Si vous ne spécifiez pas le nom d'hôte ici, vous devez spécifier le nom d'hôte dans le champ application de votre fichier app.yaml ou spécifier votre ID de projet lorsque vous déployez votre application App Engine. hostname='your_app_id.appspot.com'
issuers Facultatif. Configurations d'émetteur JWT personnalisées. Il doit s'agir d'un dictionnaire mappant les noms d'émetteurs aux objets endpoints.Issuer. issuers={"auth0": endpoints.Issuer("https://test.auth0.com", "https://test.auth0.com/.well-known/jwks.json")}
name Obligatoire. Nom de l'API, utilisé comme préfixe pour toutes les méthodes et tous les chemins d'accès de l'API. La valeur name :
  • doit commencer par une lettre minuscule ;
  • doit correspondre à l'expression régulière [a-z]+[A-Za-z0-9], c'est-à-dire que le reste du nom peut être composé de lettres ou de chiffres en majuscules et minuscules.
Pour permettre le déploiement de plusieurs API au sein d'un même service, tous les noms d'API doivent correspondre à l'expression régulière [a-z][a-z0-9]{0,39}. En d'autres termes, leur nom doit commencer par une lettre minuscule, le reste des caractères doivent être des lettres minuscules ou des chiffres, et la longueur maximale est de 40 caractères.		 name='yourApi' ou name='yourapi'
limit_definitions Facultatif. Permet de définir des quotas pour votre API. Pour plus d'informations, consultez la page limit_definitions.
owner_domain Facultatif. Nom de domaine de l'entité propriétaire de l'API. Utilisé conjointement avec owner_name pour fournir des pistes permettant de nommer correctement la bibliothèque cliente lorsqu'elle est générée pour cette API. Le chemin d'accès au package est l'inverse des arguments owner_domain et package_path le cas échéant. La valeur par défaut est appid.apppost.com. owner_domain='your-company.com'
owner_name Facultatif. Nom de l'entité propriétaire de l'API. Utilisé conjointement avec owner_domain pour fournir des pistes permettant de nommer correctement la bibliothèque cliente lorsqu'elle est générée pour cette API. owner_name='Your-Company'
package_path Facultatif. Utilisé pour étendre la portée du "package" auquel l'API appartient, avec des valeurs séparées par / spécifiant des regroupements logiques d'API.

Par exemple, si vous spécifiez cloud/platform, le chemin de la bibliothèque cliente est défini sur cloud/platform/<ApiName> et celui du package de la bibliothèque cliente est défini sur cloud.plaform.<ApiName>.		 package_path='cloud/platform'
scopes S'il n'est pas renseigné, la valeur par défaut est le champ d'application de l'adresse e-mail (https://www.googleapis.com/auth/userinfo.email), obligatoire pour OAuth. Vous pouvez le remplacer pour spécifier davantage de champs d'application OAuth 2.0 si vous le souhaitez. Vous pouvez également remplacer les champs d'application spécifiés ici par une méthode d'API particulière, en spécifiant des champs d'application différents dans le décorateur @endpoints.method. Toutefois, si vous définissez plusieurs champs d'application, gardez à l'esprit que la vérification du champ d'application est validée si le jeton est attribué à n'importe lequel des champs d'application spécifiés. Pour exiger plusieurs champs d'application, une seule chaîne doit être spécifiée avec un espace entre chaque champ d'application. scopes=['ss0', 'ss1 and_ss2']
title Facultatif. Le texte affiché dans l'explorateur d'API en tant que titre de votre API et exposé dans les services de découverte et d'annuaire. title='My Backend API'
version Obligatoire. Spécifie votre version Cloud Endpoints. Cette valeur apparaît dans le chemin de l'API. Si la chaîne de version est compatible avec le SemVer standard, seul le numéro de version majeure figure dans le chemin d'accès de l'API au moment de son déploiement. Par exemple, une API nommée echo de version 2.1.0 doit avoir un chemin d'accès semblable à /echo/v2. Si vous mettez à jour l'API echo vers la version 2.2.0 et que vous déployez une modification rétrocompatible, le chemin d'accès demeure /echo/v2. Vous pouvez ainsi mettre à jour le numéro de version de l'API lors d'une modification rétrocompatible, sans rompre les chemins d'accès existants pour vos clients. En revanche, si vous mettez à jour l'API echo vers la version 3.0.0 (dans le cadre du déploiement d'une modification destructive), le chemin d'accès est remplacé par /echo/v3. version='v1' ou version='2.1.0'

limit_definitions

Pour définir des quotas pour votre API, spécifiez l'argument facultatif limit_definitions dans @endpoints.api. Pour configurer un quota, vous devez également :

  • installer la version 2.4.5 ou ultérieure de la bibliothèque de frameworks Endpoints ;
  • ajoutez l'argument metric_costs au décorateur de méthode pour chaque méthode à laquelle vous souhaitez appliquer un quota.

Pour plus d'informations sur les étapes nécessaires à la configuration d'un quota, consultez la page Configurer des quotas.

Spécifiez une liste d'une ou plusieurs instances LimitDefinition, comme suit :

quota_limits = [
              endpoints.LimitDefinition(
                "name",
                "Display name",
                limit)
]

Chaque instance LimitDefinition doit avoir les valeurs suivantes :

Élément Description
name Nom du compteur de requêtes de l'API. En règle générale, il s'agit du type de requête (par exemple, "read-requests" ou "write-requests") qui identifie de manière unique le quota.
Display name

Texte affiché pour identifier le quota sur l'onglet Quotas de la page Endpoints > Services. Ce texte est également affiché pour les utilisateurs de votre API sur la page Quotas dans "IAM et administration" et dans "API et services". Le nom à afficher doit comporter 40 caractères au maximum.

Par souci de lisibilité, le texte "par minute par projet" est automatiquement ajouté au nom à afficher sur les pages "Quotas". Pour maintenir la cohérence avec les noms d'affichage des services Google répertoriés dans les pages "Quotas que les consommateurs de votre API voient, nous vous recommandons ce qui suit pour le nom d'affichage :

  • Utilisez "Requests" lorsque vous n'avez qu'une seule métrique.
  • Lorsque vous disposez de plusieurs métriques, chacune doit décrire le type de requête et contenir le mot "requests" (par exemple "read-requests" ou "write-requests").
  • Utilisez "Quota units" au lieu de "Requests" lorsque l'un des coûts de ce quota est supérieur à 1.

limit Nombre entier représentant le nombre maximal de requêtes par minute par projet client pour le quota.

Exemple

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 clients et audiences autorisés

Pour l'authentification OAuth2, un jeton OAuth2 est émis pour un ID client spécifique, ce qui signifie que vous pouvez utiliser cet ID client pour restreindre l'accès à vos API. Lorsque vous enregistrez une application Android dans la console Google Cloud, vous créez un ID client pour celle-ci. Cet ID client est celui qui demande un jeton OAuth2 à Google à des fins d'authentification. Lorsque l'API backend est protégée par authentification, un jeton d'accès OAuth2 est envoyé et ouvert par Endpoints Frameworks pour App Engine, puis l'ID client est extrait du jeton et comparé à la liste d'ID clients acceptables du backend (liste allowed_client_ids).

La liste allowed_client_ids doit contenir tous les ID client que vous avez obtenus via la console Google Cloud pour vos applications clientes Web, Android et autres. (Cela signifie que les clients doivent être connus au moment de la création de l'API.) Si vous spécifiez une liste vide, aucun client ne peut accéder à l'API.

Vous devez appeler endpoints.get_current_user() dans chaque méthode d'API pour laquelle vous souhaitez vérifier l'authentification. Pour plus d'informations, consultez la page Authentifier les utilisateurs.

Si vous utilisez l'argument allowed_client_ids et que vous souhaitez tester les appels authentifiés à votre API à l'aide de l'explorateur d'API, vous devez indiquer son ID client dans la liste des éléments allowed_client_ids en spécifiant la constante endpoints.API_EXPLORER_CLIENT_ID. Si allowed_client_ids ne contient que endpoints.API_EXPLORER_CLIENT_ID et que vous déployez votre API, celle-ci reste publiquement découvrable et accessible dans l'explorateur d'API.

À propos des audiences

La liste allowed_client_ids protège l'API backend des clients non autorisés. Une protection supplémentaire est cependant nécessaire pour protéger les clients, afin que leur jeton d'authentification ne fonctionne que pour l'API backend prévue. Pour les clients Android, ce mécanisme est l'argument audiences, dans lequel vous spécifiez l'ID client de l'API backend.

Notez que lorsque vous créez un projet dans la console Google Cloud, un ID client par défaut est automatiquement créé et nommé pour être utilisé par le projet. Lorsque vous importez l'API backend dans App Engine, elle utilise cet ID client. Il s'agit de l'ID client Web mentionné dans l'API auth.

Émetteur de jeton d'authentification tiers

Si votre application accepte les jetons d'authentification autres que les jetons d'ID Google et générés par des émetteurs tiers, vous devez définir correctement les arguments audiences et issuers dans @endpoints.api pour fournir les informations sur les émetteurs tiers. Exemple :

@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):

Définir une méthode d'API (@endpoints.method)

Vous pouvez définir les paramètres audiences, scopes et allowed_client_ids pour l'ensemble de l'API via @endpoints.api ou, dans le cas d'une méthode, via @endpoints.method. Si ces paramètres sont spécifiés au niveau de l'API et au niveau de la méthode, les paramètres au niveau de la méthode remplacent les paramètres au niveau de l'API.

Pour créer une méthode dans votre API, ajoutez un décorateur à la méthode Python correspondante à l'aide de @endpoints.method, en fournissant les arguments nécessaires pour configurer l'utilisation de la méthode. Par exemple, spécifiez les classes Message de requête et de réponse à utiliser.

Les arguments disponibles sont répertoriés dans le tableau suivant :

Arguments @endpoints.method Description Exemple
allowed_client_ids Paramètre remplaçant l'attribut équivalent spécifié dans @endpoints.api. Pour plus d'informations, consultez la section ID clients et audiences autorisés. ['1-web-apps.apps.googleusercontent.com', '2-android-apps.apps.googleusercontent.com']
api_key_required Facultatif. Utilisé pour limiter l'accès aux requêtes fournissant une clé API. api_key_required=True
audiences Remplace l'argument équivalent spécifié dans @endpoints.api. Pour plus d'informations, consultez la section ID clients et audiences autorisés. ['1-web-apps.apps.googleusercontent.com']
metric_costs Facultatif. Indique que la méthode a une limite de quota. Il doit s'agir d'un dictionnaire contenant les paires valeur/clé suivantes :
  • name : nom que vous avez spécifié dans l'argument limit_definitions du décorateur d'API.
  • cost : entier indiquant le coût de chaque requête. Le coût permet aux méthodes de consommer à des taux différents sur un même quota. Par exemple, si un quota a une limite de 1 000 et un coût de 1, l'application appelante peut effectuer 1 000 requêtes par minute avant de dépasser la limite. Avec un coût de 2 pour le même quota, une application appelante ne peut effectuer que 500 demandes par minute avant de dépasser la limite.
 metric_costs={'read-requests': 1}
http_method Méthode HTTP à utiliser. Si vous ne définissez pas cette valeur, la valeur par défaut est 'POST'. 'GET'
name Nom alternatif pour cette méthode. La valeur name :
  • doit commencer par une minuscule ;
  • doit correspondre à l'expression régulière [a-z]+[A-Za-z0-9]*.
 'yourApi'
path Chemin d'URI permettant d'accéder à cette méthode. Si vous ne définissez pas cet argument, le nom de la méthode Python est utilisé. Si vous envisagez d'ajouter la gestion de l'API, n'ajoutez pas de barre oblique finale au chemin. 'yourapi/path'
Classe Request Message Classe Request Message Google Protocol RPC à utiliser dans l'appel de méthode. Vous pouvez également fournir manuellement le nom de la classe. YourRequestClass
Classe Response Message Classe Response Message Google Protocol RPC à utiliser dans l'appel de méthode. Vous pouvez également fournir manuellement le nom de la classe. YourResponseClass

Utiliser ResourceContainer pour les arguments de chemin d'accès ou de chaîne de requête

Si la requête contient des arguments de chemin d'accès ou de chaîne de requête, vous ne pouvez pas utiliser une simple classe Message comme décrit dans la section Créer l'API. À la place, vous devez utiliser une classe ResourceContainer, comme suit :

  1. Définissez une classe Message contenant tous les arguments transmis dans le corps de la requête. Si aucun argument ne figure dans le corps de la requête, vous n'avez pas besoin de définir une classe Message : utilisez simplement message_types.VoidMessage. Exemple :

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

    message = messages.StringField(1)

  2. Définissez un élément ResourceContainer avec la classe Message que vous avez définie à l'étape précédente comme premier paramètre. Spécifiez les arguments de chemin d'accès et de chaîne de requête dans les paramètres suivants. Exemple :

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

    où le premier argument est la classe Message pour les données du corps de la requête, et times est un nombre attendu dans le chemin d'accès ou la chaîne accompagnant la requête.

  3. Fournissez ResourceContainer à la méthode traitant la requête, en remplaçant le premier paramètre (la classe Message de la requête) spécifié à cet emplacement. Cet extrait montre à la fois l'élément ResourceContainer et l'élément 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. Ajoutez le paramètre path tel qu'indiqué ici pour inclure votre API.

  5. Si l'élément ResourceContainer nécessite un argument, une requête client doit l'inclure soit dans une chaîne de requête (par exemple, yourApi?times=2), soit dans le chemin d'URL (par exemple, yourApi/2). Cependant, pour que votre API reçoive une valeur d'un argument via le chemin d'URL, vous devez également ajouter le nom de l'argument au chemin d'API, comme illustré ci-dessus pour l'argument {times} dans path='yourApi/{times}.

Étapes suivantes