Règle PythonScript

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Quoi

La règle de script Python vous permet d'ajouter une fonctionnalité Python personnalisée à votre flux de proxy d'API, en particulier lorsque la fonctionnalité dont vous avez besoin dépasse les règles Apigee prêtes à l'emploi.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

La compatibilité avec le langage Python est fournie via Jython version 2.5.2. Les bibliothèques tierces que vous ajoutez doivent être en "Python pur" (mises en œuvre uniquement en Python). Pour en savoir plus sur l'ajout de bibliothèques, consultez la section Fichiers de ressources.

Remarque : Cette fonctionnalité peut ne pas être disponible dans tous les forfaits Edge. Pour savoir quel forfait inclut cette fonctionnalité, consultez la page https://cloud.google.com/apigee/pricing/.

Une règle Python ne contient aucun code réel. À la place, une règle Python référence une ressource Python et définit l'étape du flux d'API où le script Python s'exécute. Vous pouvez importer votre script via l'éditeur de proxy de l'UI Apigee ou l'inclure dans le répertoire /resources/py des proxys d'API que vous développez localement.

AVERTISSEMENT :
Vous devez limiter ou désactiver l'accès SSH à vos ressources de sécurité pour empêcher cette règle d'être utilisée pour accéder aux fichiers internes, aux informations utilisateur actuelles, à la liste de processus, ou à l'utilisation du processeur/de la mémoire.

Exemples

Règles et script Python

Règle de script Python

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Script name="Python-1">
        <DisplayName>Python-1</DisplayName>
        <ResourceURL>py://myscript.py</ResourceURL>
</Script>

Dans cet exemple, l'élément ResourceURL spécifie la ressource de script Python appropriée.

Script Python

Cet exemple montre ce que vous pouvez inclure dans le script Python lui-même.

import base64

username = flow.getVariable("request.formparam.client_id")
password = flow.getVariable("request.formparam.client_secret")

base64string = base64.encodestring('%s:%s' % (username, password))[:-1]
authorization = "Basic "+base64string

flow.setVariable("authorizationParam",authorization)

Documentation de référence des éléments

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Script name="Python-1">
    <DisplayName>Python-1</DisplayName>
    <ResourceURL>py://myscript.py</ResourceURL>
    <IncludeURL>py://myscript_dependency.py</IncludeURL>
</Script>

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Attribut	Description	Par défaut	Presence
name	Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.	N/A	Obligatoire
continueOnError	Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également : Les règles d'erreur sont déclenchées UNIQUEMENT en état d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel	false	Facultatif
enabled	Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.	true	Facultatif
async	Cet attribut est obsolète.	false	Obsolète

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Par défaut	N/A Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.
Presence	Facultatif
Type	Chaîne

Élément <ResourceURL>

Cet élément spécifie le fichier Python principal qui sera exécuté dans le flux d'API. Vous pouvez stocker ce fichier au niveau du proxy d'API (sous /apiproxy/resources/py dans le groupe de proxys d'API ou dans la section Scripts du volet de navigation de l'éditeur de proxy d'API), ou aux niveaux de l'organisation ou de l'environnement afin de le réutiliser sur plusieurs proxys d'API, comme décrit dans la section Fichiers de ressources. Votre code peut utiliser les objets, les méthodes et les propriétés du modèle d'objet JavaScript.

<ResourceURL>py://myscript.py</ResourceURL>

Valeur par défaut :	Aucune
Présence :	Obligatoire
Type :	Chaîne

Élément <IncludeURL>

Spécifie un fichier Python à charger en tant que dépendance au fichier Python principal spécifié avec l'élément <ResourceURL>. Les scripts seront évalués dans l'ordre dans lequel ils sont répertoriés dans la règle.

Incluez plusieurs ressources de dépendance Python avec des éléments <IncludeURL> supplémentaires.

Avertissement : Si vos fichiers Python sont stockés au niveau de l'organisation ou de l'environnement, vérifiez qu'ils ont été importés correctement avec cURL à l'aide de l'option -F ou en tant que pièce jointe via un client REST. La valeur de Content-Type est multipart/form-data. Pour en savoir plus, consultez la section Fichiers de ressources.

<IncludeURL>py://myscript_dependency.py</IncludeURL>

Valeur par défaut :	Aucune
Présence :	Facultatif
Type :	Chaîne

Codes d'erreur

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Conseil : Vous avez besoin d'aide pour résoudre une erreur ? Cliquez sur dans la colonne "Corriger" pour obtenir des informations de dépannage détaillées.

Code d'erreur	État HTTP	Cause	Corriger
steps.script.ScriptEvaluationFailed	500	La règle PythonScript peut générer plusieurs types d'erreurs différents ScriptExecutionFailed. Les types d'erreurs courants incluent NameError et ZeroDivisionError.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Conseil : Vous avez besoin d'aide pour résoudre une erreur ? Cliquez sur à côté de la description de la cause de l'erreur pour accéder à la page de dépannage.

Nom de l'erreur	Cause	Corriger
InvalidResourceUrlFormat	Si le format de l'URL de la ressource spécifiée dans l'élément <ResourceURL> ou <IncludeURL> de la règle PythonScript n'est pas valide, alors le déploiement du proxy d'API échoue.
InvalidResourceUrlReference	Si les éléments <ResourceURL> ou <IncludeURL> font référence à un fichier PythonScript qui n'existe pas, alors le déploiement du proxy d'API échoue. Le fichier source référencé doit exister au niveau du proxy d'API, de l'environnement ou de l'organisation.

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur au moment de l'exécution. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables	Lieu	Exemple
fault.name="fault_name"	fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur.	fault.name Matches "ScriptExecutionFailed"
pythonscript.policy_name.failed	policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur.	pythonscript.PythonScript-1.failed = true

Exemple de réponse d'erreur

Remarque : Pour le traitement des erreurs, la meilleure pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Pythonscript runtime error: "ReferenceError: "status" is not defined.\"",
    "detail": {
      "errorcode": "steps.script.ScriptExecutionFailed"
    }
  }
}

Exemple de règle de défaillance

<FaultRule name="PythonScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(pythonscript.PythonScript-1.failed = true) </Condition>
</FaultRule>