Règle AssignMessage

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

Consultez la documentation d'Apigee Edge.

Objet

La règle AssignMessage peut modifier un message de requête ou de réponse existant, ou créer un nouveau message de requête ou de réponse dans le cadre d'un flux de proxy d'API. La règle vous permet d'effectuer les actions suivantes sur ces messages :

• Ajouter de nouveaux paramètres de formulaire, d'en-têtes ou de requête à un message.
• Copier des propriétés existantes d'un message à un autre
• Supprimer des en-têtes, des paramètres de requête, des paramètres de formulaire et des charges utiles de message d'un message
• Définir la valeur des propriétés existantes dans un message.

AssignMessage vous permet également de définir des variables de contexte arbitraires, indépendamment des opérations ci-dessus qui peuvent s'appliquer à un message.

Avec le paramètre AssignMessage, vous pouvez ajouter, modifier ou supprimer les propriétés de la requête ou de la réponse. Vous pouvez également utiliser la règle AssignMessage pour créer un message de requête ou de réponse personnalisé et le transmettre à une autre cible, comme décrit dans la section Créer des messages de requête personnalisés.

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.

Cas d'utilisation

Dans de nombreuses situations, vous souhaiterez peut-être modifier une requête ou un message de réponse lors du traitement par Apigee. Exemple :

• Définissez une valeur par défaut pour un paramètre de chaîne de requête ou un autre type d'entrée.
• Supprimez les en-têtes HTTP d'un message de requête avant que le message ne soit transféré au service de backend.
• Ajoutez des en-têtes HTTP avant qu'une réponse ne soit envoyée à l'application grand public.
• Insérez le contenu des messages JSON ou XML avant d'envoyer une réponse.
• Générez des messages de requête ou de réponse complets. Par exemple, vous pouvez utiliser une règle ServiceCallout pour appeler une API distante à partir d'un proxy d'API. La règle AssignMessage vous permet de créer un message de requête personnalisé et de l'attribuer à une variable. Utilisez ensuite ServiceCallout pour envoyer ce message à l'API distante.
• Ajoutez des en-têtes aux requêtes et aux réponses pour le débogage et le dépannage.

Vidéos

Regardez les vidéos suivantes pour en savoir plus sur la règle AssignMessage.

Vidéo	Description
Pourquoi utiliser la règle d'attribution de messages	Découvrez les avantages de la règle AssignMessage pour modifier la requête ou la réponse API sans modifier le code du backend.
Copier des éléments d'API à l'aide de la règle AssignMessage	Copiez des éléments à partir d'une requête ou d'une réponse d'API, puis créez une nouvelle requête ou un objet de réponse à l'aide de la règle AssignMessage.
Supprimer des éléments d'API à l'aide de la règle AssignMessage	Supprimez des éléments d'API et modifiez l'API avant qu'elle atteigne le backend cible à l'aide de la règle AssignMessage.
Ajouter et définir des éléments d'API à l'aide de la règle AssignMessage	Modifiez la requête ou la réponse de l'API en ajoutant des paramètres de requête, des en-têtes, des paramètres de formulaire ou des charges utiles à l'aide de la règle AssignMessage.
Créer des variables personnalisées à l'aide de la règle AssignMessage	Définissez des variables de flux personnalisées à l'aide de la règle AssignMessage et exploitez les variables d'autres règles dans le proxy d'API.
Créer des objets de requête ou de réponse à l'aide de la règle AssignMessage	Créez des objets de requête ou de réponse d'API à l'aide de la règle AssignMessage au moment de l'exécution de l'API.
Créer une API fictive à l'aide de la règle AssignMessage	Créez une simple API REST fictive en ajoutant la règle AssignMessage dans le flux de réponse.
Définir ou modifier la charge utile à l'aide de la règle AssignMessage	Convertissez la requête REST en requête SOAP en définissant la charge utile SOAP à l'aide de la règle AssignMessage au moment de l'exécution de l'API.

La règle AssignMessage peut créer ou modifier des variables de flux avec les éléments enfants suivants :

• <Add>
• <Copy>
• <Set>
• <Remove>
• <AssignTo>
• <AssignVariable>

L'ordre dans lequel vous organisez les éléments <Add>, <Copy>, <Set> et <Remove> sont importants. La règle exécute ces actions dans l'ordre dans lequel elles apparaissent dans la configuration de la règle. Si vous devez supprimer tous les en-têtes, puis définir un en-tête spécifique, vous devez inclure l'élément <Remove> avant l'élément <Set>.

Élément <AssignMessage>

Définit une stratégie AssignMessage.

Valeur par défaut	Consultez l'onglet Règles par défaut ci-dessous.
Obligatoire ?	Obligatoire
Type	Objet complexe
Élément parent	ND
Éléments enfants	<Add> <AssignTo> <AssignVariable> <Copy> <DisplayName> <IgnoreUnresolvedVariables> <Remove> <Set>

L'élément <AssignMessage> utilise la syntaxe suivante :

Syntaxe

L'élément <AssignMessage> utilise la syntaxe suivante :

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- All AssignMessage child elements are optional -->
  <Add>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Add>

  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>

  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
    <Ref>SOURCE_VARIABLE</Ref>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>

  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Path>[false|true]</Path>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>

  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>

  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>

  <Set>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <Path>PATH</Path>
    <Payload contentType="CONTENT_TYPE" variablePrefix="PREFIX"
        variableSuffix="SUFFIX">NEW_PAYLOAD</Payload>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
    <StatusCode>HTTP_STATUS_CODE or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>

</AssignMessage>

Règle par défaut

L'exemple suivant montre les paramètres par défaut lorsque vous ajoutez une règle AssignMessage à votre flux dans l'interface utilisateur d'Apigee :

<AssignMessage continueOnError="false" enabled="true" name="assign-message-default">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <Copy source="request">
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <Payload/>
    <Verb/>
    <StatusCode/>
    <Path/>
  </Copy>
  <Remove>
    <Headers>
      <Header name="h1"/>
    </Headers>
    <QueryParams>
      <QueryParam name="q1"/>
    </QueryParams>
    <FormParams>
      <FormParam name="f1"/>
    </FormParams>
    <Payload/>
  </Remove>
  <Add>
    <Headers/>
    <QueryParams/>
    <FormParams/>
  </Add>
  <Set>
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <!-- <Verb>GET</Verb> -->
    <Path/>
  </Set>
  <AssignVariable>
    <Name>name</Name>
    <Value/>
    <Ref/>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Lorsque vous insérez une nouvelle stratégie AssignMessage dans l'interface utilisateur d'Apigee, le modèle contient des bouchons pour toutes les opérations possibles. En règle générale, vous devez sélectionner les opérations que vous souhaitez effectuer avec cette règle et supprimer le reste des éléments enfants. Par exemple, si vous souhaitez effectuer une opération de copie, utilisez l'élément <Copy> et supprimez <Add>, <Remove> et d'autres éléments enfants de la règle pour la rendre plus lisible.

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut	Par défaut	Obligatoire ?	Description
name	ND	Obligatoire	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 avec un nom différent, en langage naturel.
continueOnError	faux	Facultatif	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 aussi : Les règles d'erreur sont déclenchées UNIQUEMENT en cas d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel
enabled	true	Facultatif	Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async	faux	Obsolète	Cet attribut est obsolète.

Le tableau suivant fournit une description détaillée des éléments enfants de <AssignMessage> :

Élément enfant	Requis ?	Description
Opérations courantes
<Add>	Facultatif	Ajoute des informations à l'objet message spécifié par l'élément <AssignTo>. <Add> ajoute au message les en-têtes ou les paramètres qui n'existent pas dans le message d'origine. Notez que <Set> fournit également cette fonctionnalité. Pour écraser des en-têtes ou des paramètres existants, utilisez l'élément <Set>.
<Copy>	Facultatif	Copie des informations à partir du message spécifié par l'attribut source dans l'objet message spécifié par l'élément <AssignTo>.
<Remove>	Facultatif	Supprime les éléments spécifiés de la variable de message spécifiée dans l'élément <AssignTo>.
<Set>	Facultatif	Remplace les valeurs des propriétés existantes dans la requête ou la réponse qui est spécifiée par l'élément <AssignTo>. <Set> écrase les en-têtes ou les paramètres déjà présents dans le message d'origine, ou en ajoute de nouveaux s'il n'y en a pas.
Autres éléments enfants
<AssignTo>	Facultatif	Indique le message sur lequel la stratégie AssignMessage fonctionne. Il peut s'agir de la requête ou de la réponse standard, ou d'un nouveau message personnalisé.
<AssignVariable>	Facultatif	Attribue une valeur à une variable de flux. Si la variable n'existe pas, <AssignVariable> la crée.
<IgnoreUnresolvedVariables>	Facultatif	Détermine si le traitement s'arrête lorsqu'une variable non résolue est rencontrée.

Chacun des éléments enfants est décrit dans les sections ci-après.

Exemples

Les exemples suivants illustrent certaines des manières dont vous pouvez utiliser la règle AssignMessage :

1 : Ajouter un en-tête

L'exemple suivant ajoute un en-tête à la requête avec l'élément <Add> :

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

2 : Supprimer la charge utile

L'exemple suivant supprime la charge utile de la réponse avec l'élément <Remove> :

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

3 : Modifier la réponse

L'exemple suivant modifie un objet de réponse existant en lui ajoutant un en-tête :

<AssignMessage name="AM-modify-response">
  <Set>
    <Headers>
      <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

Cet exemple ne crée pas de message. À la place, il modifie un message de réponse existant en ajoutant un en-tête HTTP.

Comme cet exemple spécifie response comme nom de variable dans l'élément <AssignTo>, cette règle modifie l'objet de réponse initialement défini avec les données renvoyées par le serveur cible.

L'en-tête HTTP ajouté au message de réponse par cette règle est dérivé d'une variable renseignée par la règle LookupCache. Par conséquent, le message de réponse modifié par cette règle d'attribution de messages contient un en-tête HTTP qui indique si les résultats ont été extraits du cache ou non. La définition d'en-têtes dans la réponse peut être utile pour le débogage et le dépannage.

Conseil : Ce modèle de définition d'en-têtes pour le débogage et le dépannage est une pratique courante. Vous pouvez voir quelle valeur d'en-tête a été renvoyée en inspectant la réponse à l'aide de l'outil Debug ou d'autres moyens.

4 : Définir un contenu dynamique

Vous pouvez utiliser la règle AssignMessage pour intégrer le contenu dynamique dans la charge utile des messages de réponse et de requête.

Pour intégrer des variables de flux dans une charge utile XML, placez la variable désignée entre accolades, comme ceci : {prefix.name}.

L'exemple suivant intègre la valeur de la variable de flux d'en-tête HTTP user-agent dans un élément XML appelé User-agent :

<AssignMessage name="AM-set-dynamic-content">
  <AssignTo>response</AssignTo>
  <Set>
    <Payload contentType="text/xml">
      <User-agent>{request.header.user-agent}</User-agent>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Pour les charges utiles JSON, vous pouvez insérer des variables à l'aide des attributs variablePrefix et variableSuffix avec des caractères de délimitation, comme illustré dans l'exemple suivant :

<AssignMessage name="set-payload">
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
  {
     "user-agent": "@request.header.user-agent#"
  }
  </Payload>
</AssignMessage>

Pour obtenir une liste complète des variables de flux, reportez-vous à la documentation de référence des variables de flux groupée).

Vous pouvez également utiliser des accolades pour insérer des variables.

5 : Supprimer le paramètre de requête

L'exemple suivant supprime le paramètre de requête apikey de la requête :

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Il est recommandé de supprimer le paramètre de requête apikey du message de requête lorsque vous utilisez la règle VerifyAPIKey pour l'authentification de l'utilisateur. Cette démarche permet d'empêcher la transmission des informations de clé sensibles à la cible principale.

6 : Définir/obtenir des variables

L'exemple suivant utilise trois règles AssignMessage :

1. Crée trois variables de flux dans la requête, avec des valeurs statiques.
2. Récupère les variables de flux de façon dynamique dans une deuxième règle du flux de requête.
3. Les définit dans la charge utile de la réponse.

<!-- Policy #1: Set variables in the request -->
<AssignMessage name="AM-set-variables">
    <!-- Create a variable named myAppSecret -->
    <AssignVariable>
        <Name>myAppSecret</Name>
        <Value>42</Value>
    </AssignVariable>
    <!-- Create a variable named config.environment -->
    <AssignVariable>
        <Name>config.environment</Name>
        <Value>test</Value>
    </AssignVariable>
    <!-- Create a variable named config.protocol -->
    <AssignVariable>
        <Name>config.protocol</Name>
        <Value>gopher</Value>
    </AssignVariable>
</AssignMessage>

Dans la première règle, l'élément <AssignVariable> crée et définit trois variables dans la requête. Chaque élément <Name> spécifie un nom de variable et <Value> spécifie la valeur.

La deuxième règle utilise l'élément <AssignVariable> pour lire les valeurs et créer trois variables :

<!-- Policy #2: Get variables from the request -->
<AssignMessage continueOnError="false" enabled="true" name="get-variables">
  <AssignTo createNew="false" transport="http" type="request"/>
  <!-- Get the value of myAppSecret and create a new variable, secret -->
  <AssignVariable>
    <Name>secret</Name>
    <Ref>myAppSecret</Ref>
    <Value>0</Value>
  </AssignVariable>
  <!-- Get the value of config.environment and create a new variable, environment -->
  <AssignVariable>
    <Name>environment</Name>
    <Ref>config.environment</Ref>
    <Value>default</Value>
  </AssignVariable>
  <!-- Get the value of config.protocol and create a new variable, protocol -->
  <AssignVariable>
    <Name>protocol</Name>
    <Ref>config.protocol</Ref>
    <Value>default</Value>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Dans la seconde règle, l'élément <Ref> fait référence à la variable source, et les éléments <Name> spécifient le nom des nouvelles variables. Si la variable référencée par l'élément <Ref> n'est pas accessible, vous pouvez utiliser la valeur spécifiée par l'élément <Value>.

Pour essayer ces règles, procédez comme suit :

1. Ajoutez les stratégies 1 et 2 au flux de requête. Veillez à placer la règle n° 1 avant la règle n° 2.
2. Ajoutez la troisième règle dans le flux response.
3. La troisième règle utilise l'élément <Set> pour ajouter les variables à la réponse. L'exemple suivant construit une charge utile XML dans la réponse renvoyée par Edge au client :

   <!-- Policy #3: Add variables to the response -->
   <AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload">
     <DisplayName>put-em-in-the-payload</DisplayName>
     <Set>
       <Payload contentType="application/xml">
         <wrapper>
           <secret>{secret}</secret>
           <config>
             <environment>{environment}</environment>
             <protocol>{protocol}</protocol>
           </config>
         </wrapper>
       </Payload>
     </Set>
     <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
     <AssignTo createNew="false" transport="http" type="response"/>
   </AssignMessage>

   Notez que la syntaxe permettant d'accéder aux variables de flux dans <Set> consiste à les placer entre accolades.

   Veillez à définir l'attribut contentType de l'élément <Payload> sur application/xml.

4. Envoyez une requête à votre proxy d'API. Exemple :

   curl -vL https://ahamilton-eval-test.apigee.net/myproxy

   Vous pouvez également lier les résultats via un utilitaire tel que xmllint pour que le code XML s'affiche dans une structure correctement formatée :

   curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -

   Le corps de la réponse doit se présenter comme suit :

   <wrapper>
     <secret>42</secret>
     <config>
       <environment>test</environment>
       <protocol>gopher</protocol>
     </config>
   </wrapper>

7 : Obtenir les en-têtes de réponse d'appel de service

Dans l'exemple suivant, supposons qu'une règle ServiceCallout figure dans la requête de proxy d'API et que la réponse à l'appel contienne plusieurs en-têtes portant le même nom (Set-Cookie). En supposant que la variable de réponse de l'appel de service est la valeur par défaut calloutResponse, la règle suivante récupère la deuxième valeur d'en-tête Set-Cookie.

<AssignMessage name="AM-Payload-from-SC-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

Pour répertorier toutes les valeurs d'en-tête, utilisez plutôt la variable suivante :

{calloutResponse.header.Set-Cookie.values}

8 : Stocker et supprimer les paramètres de formulaire, les en-têtes et les paramètres de requête

Si vous souhaitez utiliser <Remove> pour supprimer vos en-têtes, vos paramètres de requête ou vos paramètres de formulaire, mais conserver l'accès à leurs valeurs plus tard dans le flux de règles, vous pouvez stocker leurs valeurs à l'aide de <AssignVariable>.

<AssignMessage async="false" continueOnError="false" enabled="true" name="AM-StoreAndRemove">
  <DisplayName>AM-StoreAndRemove</DisplayName>
  <AssignVariable>
    <Name>var_grant_type</Name>
    <Ref>request.formparam.grant_type</Ref>
  </AssignVariable>
  <Remove>
    <Headers/>
    <FormParams/>
    <Payload/>
  </Remove>
  <Set>
    <Headers>
      <Header name="Content-Type">application/x-www-form-urlencoded</Header>
      <Header name="Accept">application/json</Header>
      <Header name="Grant-Type">{var_grant_type}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Remarque : Les paramètres de formulaire, les en-têtes et les paramètres de requête supprimés à l'aide de <Remove> dans la règle d'attribution de message ne sont accessibles qu'une fois le flux de règles terminé, sauf si leurs valeurs sont stockées dans des variables, comme décrit dans cet exemple.

Chaque élément enfant de cette référence comporte des exemples supplémentaires. Pour obtenir d'autres exemples, consultez la section Exemple AssignMessage sur GitHub.

Référence d'élément enfant

Cette section décrit les éléments enfants de <AssignMessage>.

<Add>

Ajoute des informations à la requête ou à la réponse, spécifiée par l'élément <AssignTo>.

L'élément <Add> ajoute les propriétés au message qui n'existent pas dans le message d'origine. Notez que <Set> fournit également cette fonctionnalité. Pour modifier les valeurs des propriétés existantes, utilisez l'élément <Set>.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Type complexe
Élément parent	<AssignMessage>
Éléments enfants	<FormParams> <Headers> <QueryParams>

L'élément <Add> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

Exemple 1

L'exemple suivant utilise l'élément <FormParams> pour obtenir les valeurs de trois paramètres de chaîne de requête de la requête initiale et les définir en tant que paramètres de formulaire sur la requête de point de terminaison cible :

<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 2

L'exemple suivant utilise l'élément <Headers> pour ajouter un en-tête partner-id à la requête qui sera envoyée au point de terminaison cible :

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 3

L'exemple suivant utilise l'élément <QueryParams> pour ajouter à la requête un seul paramètre de requête doté d'une valeur statique :

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

Cet exemple utilise <Add> dans le flux de requêtes. Si vous consultez les résultats dans un outil tel que la présentation de Debug, la requête envoyée à https://example-target.com/get devient https://example-target.com/get?myParam=42.

Les éléments enfants de <Add> acceptent la substitution de chaîne dynamique, appelée modélisation de message.

<FormParams> (enfant de <Add>)

Ajoute des paramètres de formulaire au message de requête. Cet élément n'a aucun effet sur le message de réponse.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <FormParam>
Élément parent	<Add>
Éléments enfants	<FormParam>

L'élément <FormParams> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>
  </Add>
</AssignMessage>

Exemple 1

L'exemple suivant ajoute un seul paramètre de formulaire (answer) et une valeur statique (42) à la requête :

<AssignMessage name="AM-add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 2

L'exemple suivant récupère la valeur du paramètre de requête name et l'ajoute à la requête en tant que paramètre de formulaire, puis le supprime :

<AssignMessage name="AM-Swap-QueryParam-to-FormParams">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
  <Remove>
    <QueryParam name="name"/>
  </Remove>
</AssignMessage>

Notez que cet exemple ne spécifie pas de cible avec <AssignTo>. Cette règle ajoute le paramètre à la requête uniquement.

Exemple 3

L'exemple suivant ajoute plusieurs paramètres de formulaire à la requête :

<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Cet exemple récupère les paramètres de chaîne de requête de la requête d'origine et les ajoute en tant que paramètres de formulaire avec des noms différents. Ensuite, les paramètres de requête d'origine sont supprimés. Apigee envoie la requête modifiée au point de terminaison cible.

Vous pouvez utiliser la page Présentation de Debug pour consulter le flux. Le corps de la requête contient les données de formulaire encodées en URL qui ont été initialement transmises en tant que paramètres de chaîne de requête :

username=nick&zip_code=90210&default_language=en

Vous ne pouvez utiliser <FormParams> que lorsque les critères suivants sont remplis :

• Verbe HTTP : POST
• Type de message : Requête
• Un des éléments suivants (ou les deux) :
  • Données de formulaire : défini sur une valeur ou sur "" (la chaîne vide). Par exemple, avec curl, ajoutez -d "" à votre requête.
  • En-tête Content-Length : défini sur 0 (si aucune donnée ne figure dans la requête d'origine, sinon, la longueur actuelle, en octets). Par exemple, avec curl, ajoutez -H "Content-Length: 0" à votre requête.

Exemple :

curl -vL -X POST -d "" -H "Content-Type: application/x-www-form-urlencoded"
  https://ahamilton-eval-test.apigee.net/am-test

Lorsque vous ajoutez <FormParams>, Apigee définit l'en-tête Content-Type de la requête sur application/x-www-form-urlencoded avant d'envoyer le message au service cible.

<Headers> (enfant de <Add>)

Ajoute des en-têtes à la requête ou à la réponse spécifiée, indiquée par l'élément <AssignTo>.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <Header>
Élément parent	<Add>
Éléments enfants	<Header>

L'élément <Headers> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
  </Add>
</AssignMessage>

Exemple 1

L'exemple suivant ajoute un en-tête partner-id au message de requête et attribue la valeur de la variable de flux verifyapikey.VAK-1.developer.app.partner-id à cet en-tête.

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

<QueryParams> (enfant de <Add>)

Ajoute des paramètres de requête à la requête. Cet élément n'a aucun effet sur une réponse.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <QueryParam>
Élément parent	<Add>
Éléments enfants	<QueryParam>

L'élément <QueryParams> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

Exemple 1

L'exemple suivant ajoute le paramètre de requête myParam à la requête et lui attribue la valeur 42 :

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

Vous ne pouvez utiliser <QueryParams> que lorsque les critères suivants sont remplis :

• Verbes HTTP : GET, POST, PATCH, DELETE
• Type de message : Requête

De plus, vous ne pouvez définir des paramètres de requête que lorsque l'attribut type de l'élément <AssignTo> est un message de requête. Les paramètres définis dans la réponse n'ont aucun effet.

Si vous définissez un tableau de paramètres de requête vide dans votre règle (<Add><QueryParams/></Add>), celle-ci n'ajoute aucun paramètre de requête. Cela revient à omettre <QueryParams>.

<AssignTo>

Détermine l'objet sur lequel agit la stratégie AssignMessage. Vous disposez des options suivantes :

• Message de requête : le request reçu par le proxy d'API
• Message de réponse : le message response renvoyé par le serveur cible
• Message personnalisé : requête ou objet de réponse personnalisé

Notez que dans certains cas, vous ne pouvez pas modifier l'objet sur lequel agit la règle AssignMessage. Par exemple, vous ne pouvez pas utiliser <Add> ou <Set> pour ajouter ou modifier des paramètres de requête (<QueryParams>) ou des paramètres de formulaire (<FormParams>) sur la réponse. Vous ne pouvez manipuler que les paramètres de requête et les paramètres de formulaire sur la requête.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Chaîne
Élément parent	<AssignMessage>
Éléments enfants	Aucun

Si vous ne spécifiez pas <AssignTo>, ou si vous spécifiez l'élément <AssignTo>, mais ne spécifiez pas de valeur textuelle pour l'élément, la règle agit sur la requête ou la réponse par défaut, à savoir : en fonction de l'emplacement d'exécution de la règle. Si la règle s'exécute dans le flux de requête, elle a une incidence sur le message de la requête. Si elle s'exécute dans le flux de réponse, la règle affecte par défaut la réponse.

L'élément <AssignTo> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>
</AssignMessage>

Exemple 1

L'exemple suivant ne spécifie aucun message dans le texte du <AssignTo>. Cela implique que la règle agira sur le message request ou response, selon l'emplacement où la règle s'exécute.

<AssignMessage name="assignto-1">
  <AssignTo createNew="false" transport="http" type="request"/> <!-- no-op -->
  ...
</AssignMessage>

Si vous spécifiez createNew="false" et que vous ne fournissez pas explicitement de nom de message, les autres attributs de <AssignTo> ne sont pas pertinents. Dans ce cas, vous pouvez omettre complètement l'élément <AssignTo>.

Exemple 2

L'exemple suivant crée un objet de requête, en remplaçant l'objet existant :

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"/>
  ...
</AssignMessage>

Lorsque vous créez un objet de requête ou de réponse, les autres éléments de la règle AssignMessage (tels que <Add>, <Set> et <Copy>) agissent sur ce nouvel objet de requête.

Vous pourrez accéder ultérieurement au nouvel objet de requête dans d'autres règles du flux ou envoyer le nouvel objet de requête à un service externe avec une règle ServiceCallout.

Exemple 3

L'exemple suivant crée un objet de requête nommé MyRequestObject :

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request">MyRequestObject</AssignTo>
  ...
</AssignMessage>

Lorsque vous créez un objet de requête ou de réponse, les autres éléments de la règle AssignMessage (tels que <Add>, <Set> et <Copy>) agissent sur ce nouvel objet de requête.

Vous pourrez accéder ultérieurement au nouvel objet de requête dans d'autres règles du flux ou envoyer le nouvel objet de requête à un service externe avec une règle ServiceCallout.

Le tableau suivant décrit les attributs de <AssignTo> :

Attribut	Description	nécessaire	Type
createNew	Détermine si cette règle crée un message lors de l'attribution de valeurs. Si la valeur est true, la règle crée une variable du type spécifié par type (request ou response). Si vous ne spécifiez pas le nom de la nouvelle variable, la règle crée un objet de requête ou de réponse basé sur la valeur de type. Attention : Lors de la création d'un objet de requête ou de réponse, l'objet de requête ou de réponse existant est supprimé et remplacé par le nouvel objet. Cela signifie que toutes les informations de l'objet sont perdues. Si la valeur est false, la règle répond de l'une des deux manières suivantes : Si <AssignTo> peut résoudre le nom de la variable dans une requête ou une réponse, le traitement se poursuit. Par exemple, si la règle se trouve dans un flux de requête, la variable est l'objet de requête. Si la règle est dans une réponse, la variable est l'objet de réponse. Si <AssignTo> ne peut être résolu ou est associé à un type qui n'est pas un message, la règle génère une erreur. Si createNew n'est pas spécifié, la règle répond de l'une des deux manières suivantes : Si <AssignTo> renvoie un message, le traitement passe à l'étape suivante. Si <AssignTo> ne peut être résolu ou est associé à un type qui n'est pas un message, une variable de type spécifiée dans type est créée.	Facultatif	Booléen
transport	Spécifie le type de transport pour le type de message de requête ou de réponse. La valeur par défaut est http (seule valeur acceptée).	Facultatif	Chaîne
type	Indique le type du nouveau message, lorsque createNew est défini sur true. Les valeurs valides sont request ou response. La valeur par défaut est request. Si vous omettez cet attribut, Apigee crée une requête ou une réponse, selon l'emplacement du flux exécuté par cette règle.	Facultatif	Chaîne

<AssignVariable>

Attribue une valeur à une variable de flux de destination (par exemple, une variable dont la valeur est définie par la règle AssignMessage). Si la variable de flux n'existe pas, <AssignVariable> la crée. Vous pouvez utiliser plusieurs éléments AssignVariable au sein de la règle AssignMessage. Ils sont exécutés dans leur ordre d'apparition au sein de la configuration de la règle.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Type complexe
Élément parent	<AssignMessage>
Éléments enfants	<Name> (obligatoire) <PropertySetRef> <Ref> <ResourceURL> <Template> <Value>

La valeur que vous attribuez à la variable de flux de destination peut être l'une des suivantes :

• Chaîne littérale : utilisez l'élément enfant <Value> pour spécifier une valeur de chaîne littérale pour la variable de flux de destination.
• Variable de flux : utilisez l'élément enfant <Ref> pour spécifier la valeur d'une variable de flux existante pour la variable de flux de destination. Pour obtenir la liste complète des variables de flux pouvant être utilisées comme source, consultez la documentation de référence sur les variables de flux.
• Ensemble de propriétés : utilisez l'élément enfant <PropertySetRef> pour récupérer la valeur d'une paire nom/clé d'un ensemble de propriétés et les stocker dans une variable de flux. Vous permet d'accéder aux ensembles de propriétés de manière dynamique.
• URL de ressource : utilisez l'élément enfant <ResourceURL> pour spécifier une URL pour une ressource textuelle, de type XSL, XSD, WSDL, JavaScript ou OpenAPI Spec. Cette action attribue le contenu de la ressource à la variable de flux nommée.
• Modèle de message : utilisez l'élément enfant <Template> pour spécifier un modèle de message pour la variable de flux de destination.

L'ordre de priorité de ces éléments enfants est le suivant : ResourceURL, Template, Ref, Value, PropertySetRef.

L'élément <AssignVariable> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
    <Ref>SOURCE_VARIABLE</Ref>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>
</AssignMessage>

Utilisez l'élément <Ref> pour spécifier la variable source. Si la variable référencée par <Ref> n'est pas accessible, Apigee utilise la valeur spécifiée par l'élément <Value>. Si vous définissez <Template>, il est prioritaire sur les éléments frères <Ref> et <Value>.

Exemple 1

L'exemple suivant définit la valeur d'une nouvelle variable, myvar, sur la valeur littérale 42 :

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

Exemple 2

L'exemple suivant attribue la valeur de la variable de flux. request.header.user-agent à la variable de flux de destination myvar et la valeur du paramètre de requête country à la variable de flux de destination Country :

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

Si l'une des attributions échoue, Apigee attribue la valeur ErrorOnCopy à la variable de flux de destination.

Si les variables de flux myvar ou Country n'existent pas, <AssignVariable> les crée.

Exemple 3

L'exemple suivant utilise l'élément enfant <Template> pour concaténer deux variables de contexte avec une chaîne littérale (un trait d'union) entre elles :

<AssignMessage name='AV-via-template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

Exemple 4

L'exemple suivant utilise <AssignVariable> pour désactiver le comportement par défaut qui consiste à propager le suffixe de chemin d'accès de la requête de proxy à la requête cible :

<AssignMessage name='AM-PathSuffixFalse'>
  <AssignVariable>
    <Name>target.copy.pathsuffix</Name>
    <Value>false</Value>
  </AssignVariable>
</AssignMessage>

Une utilisation courante de <AssignVariable> consiste à définir une valeur par défaut pour un paramètre de requête, un en-tête ou une autre valeur pouvant être transmise avec la requête. Pour ce faire, vous pouvez combiner les éléments enfants <Ref> et <Value>. Pour en savoir plus, consultez les exemples sur <Ref>.

<Name> (enfant de <AssignVariable>)

Spécifie le nom de la variable de flux de destination (par exemple, la variable dont la valeur est définie par la règle AssignMessage). Si la variable nommée <Name> n'existe pas, la règle crée une variable portant ce nom.

Valeur par défaut	ND
Obligatoire ?	Obligatoire
Type	Chaîne
Élément parent	<AssignVariable>
Éléments enfants	Aucune

L'élément <Name> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
  </AssignVariable>
</AssignMessage>

Exemple 1

L'exemple suivant spécifie la variable de destination en tant que myvar et la définit sur la valeur littérale 42 :

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

Si le fichier myvar n'existe pas, <AssignVariable> le crée.

Remarque : Le nom ratelimit est réservé. Pour en savoir plus, consultez la section sur les règles de quota générant une exception NullPointerException dans la communauté Apigee.

<PropertySetRef> (enfant de <AssignVariable>)

Cet élément vous permet de récupérer la valeur d'une paire nom/clé d'un ensemble de propriétés de façon dynamique. Pour en savoir plus sur les ensembles de propriétés, consultez l'article Gérer les ensembles de propriétés.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Chaîne
Élément parent	<AssignVariable>
Éléments enfants	None

Un ensemble de propriétés est constitué d'une paire nom/clé. Exemple : propset1.id=12345, où propset1 est le nom de l'ensemble de propriétés, id une clé et 12345 la valeur de la clé.

L'élément enfant PropertySetRef vous permet de sélectionner dynamiquement des noms et/ou des clés d'ensembles de propriétés. Supposons que vous ayez 200 règles de routage dans un fichier d'ensemble de propriétés. Vous pouvez accéder aux règles des ensembles de propriétés comme suit, où routingrules est le nom de l'ensemble de propriétés et rule1, rule2 et rulen sont des clés :

propertyset.routingrules.rule1
propertyset.routingrules.rule2
propertyset.routingrules.rulen

Pour accéder à ces propriétés dans un flux de proxy d'API, vous devez savoir quelle règle vous souhaitez sélectionner au moment de la conception. Toutefois, supposons que le nom de la règle figure dans l'en-tête de la requête ou dans la charge utile. Pour sélectionner la règle, vous pouvez par exemple utiliser une règle JavaScript avec un code tel que celui-ci :

context.getVariables("propertyset.routingrules." + ruleName); //assuming ruleName was populated earlier.

D'autre part, la fonctionnalité AssignMessage de PropertySetRef vous permet de sélectionner une clé de propriété de manière dynamique sans recourir à JavaScript.

Vous pouvez utiliser une combinaison de variables de flux et de valeurs de chaîne littérales dans l'élément <PropertySetRef>. Pour plus d'informations, consultez les exemples.

Remarque : Lorsque vous utilisez cette fonctionnalité, ne faites pas référence à la propriété définie à l'aide du préfixe propertyset, comme dans propertyset.PROPNAME.KEY. Le préfixe propertyset est utilisé.

L'élément <PropertySetRef> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
  </AssignVariable>
</AssignMessage>

Exemple 1

Cet exemple attribue la valeur d'une clé d'un ensemble de propriétés à une variable de flux. Dans ce cas, le nom de l'ensemble de propriétés est obtenu à partir de l'en-tête propset_name, la clé est fournie dans l'en-tête propset_key et la valeur attribuée à la clé est stockée dans la variable flow_variable.

<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <AssignVariable>
    <Name>flow_variable</Name>
    <PropertySetRef>{request.header.propset_name}.{request.header.propset_key}</PropertySetRef>
  </AssignVariable>
</AssignMessage>

Vous pouvez utiliser n'importe quelle combinaison de variables de flux et de chaînes littérales dans l'élément <PropertySetRef>.

Exemple 2

Cet exemple attribue la valeur d'une clé d'un ensemble de propriétés à une variable de flux à l'aide d'un nom de clé fixe (chaîne littérale). Dans ce cas, le nom de l'ensemble de propriétés est obtenu à partir de l'en-tête propset_name, la clé est la chaîne littérale key1 et la valeur attribuée à la clé est stockée dans la variable flow_variable.

<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <AssignVariable>
    <Name>flow_variable</Name>
    <PropertySetRef>{request.header.propset_name}.key1</PropertySetRef>
  </AssignVariable>
</AssignMessage>

Vous pouvez utiliser n'importe quelle combinaison de variables de flux et de chaînes littérales dans l'élément <PropertySetRef>.

<Ref> (enfant de <AssignVariable>)

Spécifie la source de l'attribution en tant que variable de flux. La variable de flux peut être l'une des variables de flux prédéfinies (répertoriées dans la documentation de référence sur les variables de flux) ou une variable de flux personnalisée que vous avez créée.

La valeur de <Ref> est toujours interprétée comme une variable de flux. Vous ne pouvez pas spécifier de chaîne littérale comme valeur. Pour attribuer une valeur de chaîne littérale, utilisez plutôt l'élément <Value>.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Chaîne
Élément parent	<AssignVariable>
Éléments enfants	Aucun

Lorsque vous spécifiez une variable de flux avec <Ref>, omettez les accolades {} que vous utilisez généralement pour référencer une variable de flux. Par exemple, pour définir la valeur de votre nouvelle variable sur la valeur de la variable de flux client.host, procédez comme suit :

  DO specify the variable name without brackets:
  <Ref>client.host</Ref>

  DO NOT use brackets:
  <Ref>{client.host}</Ref>

Pour définir une valeur par défaut pour la variable de flux de destination, utilisez <Value> conjointement avec <Ref>. Si la variable de flux spécifiée par <Ref> n'existe pas, ne peut pas être lue ou si sa valeur est nulle, Apigee attribue la valeur de <Value> à la variable de flux de destination.

L'élément <Ref> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <Ref>SOURCE_VARIABLE</Ref>
  </AssignVariable>
</AssignMessage>

Exemple 1

L'exemple suivant attribue la valeur de la variable de flux request.header.user-agent à la variable de flux de destination myvar et la valeur du paramètre de requête country à la variable Country :

<AssignMessage name="assignvariable-4">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

Dans cet exemple, Apigee n'a pas de valeur par défaut (ou valeur de remplacement) spécifiée pour l'une ou l'autre des attributions.

Exemple 2

L'exemple suivant attribue la valeur de la variable de flux request.header.user-agent à la variable de flux de destination myvar et la valeur du paramètre de requête country à la variable Country :

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

Dans cet exemple, si les valeurs de la variable de flux request.header.user-agent ou du paramètre de requête Country sont NULL, illisibles ou incorrectes, Apigee attribue la valeur ErrorOnCopy aux nouvelles variables.

Exemple 3

Un cas d'utilisation courant de <AssignVariable> consiste à définir la valeur par défaut d'un paramètre de requête, d'un en-tête ou d'une autre valeur pouvant être transmise avec la requête. Par exemple, vous créez un proxy d'API météo pour lequel la requête utilise un seul paramètre de requête nommé w. Ce paramètre contient l'ID de la ville pour laquelle vous souhaitez obtenir la météo. L'URL de la requête prend la forme suivante :

http://myCO.com/v1/weather/forecastrss?w=CITY_ID

Pour définir une valeur par défaut pour w, créez une règle AssignMessage comme suit :

<AssignMessage continueOnError="false" enabled="true" name="assignvariable-3">
  <AssignTo createNew="false" transport="http" type="request"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>request.queryparam.w</Name>
    <Ref>request.queryparam.w</Ref>
    <Value>12797282</Value>
  </AssignVariable>
</AssignMessage>

Dans cet exemple, <AssignVariable> récupère la valeur de request.queryparam.w et l'attribue à lui-même. Si la variable de flux est nulle, ce qui signifie que le paramètre de requête w a été omis de la requête, cet exemple utilise la valeur par défaut de l'élément <Value>. Par conséquent, vous pouvez envoyer une requête à ce proxy d'API qui omet le paramètre de requête w :

http://myCO.com/v1/weather/forecastrss

mais renvoie toujours un résultat valide.

La valeur de <Ref> doit être une variable de flux, telle qu'une propriété de request, response ou target ou le nom d'une variable de flux personnalisée.

Si vous spécifiez une variable de flux qui n'existe pas pour la valeur de <Ref>, et que la valeur de <IgnoreUnresolvedVariables> est false, Apigee génère une erreur.

<ResourceURL> (enfant de <AssignVariable>)

Spécifie l'URL d'une ressource de texte comme source de l'attribution de variable. Apigee charge la variable de flux spécifiée dans <Name> avec le contenu de la ressource référencée. La ressource peut être de type XSD, XSL, WSDL, JavaScript, Property Set ou Spécification OpenAPI.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Chaîne
Élément parent	<AssignVariable>
Éléments enfants	Aucun

Si la ressource spécifiée par <ResourceURL> n'existe pas, alors : si la valeur de <IgnoreUnresolvedVariables> est true, Apigee attribue la valeur null à la variable de flux de destination, tandis que si la valeur de <IgnoreUnresolvedVariables> est false, Apigee génère une erreur.

L'élément <ResourceURL> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
  </AssignVariable>
</AssignMessage>
      

La valeur de texte utilise une valeur de chaîne et est interprétée comme un modèle de message. Les exemples suivants sont valides :

<ResourceURL>jsc://my-js-file.js</ResourceURL>
<ResourceURL>wsdl://{variable-goes-here}</ResourceURL>
<ResourceURL>{variable-goes-here}</ResourceURL>

Exemple 1

L'exemple suivant attribue la valeur d'une ressource JSON chargée dans le proxy du dossier jsc dans la variable de flux assigned-variable :

<AssignMessage name='AM-From-ResourceURL-Proxy-JSC'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>jsc://settings.json</ResourceURL>
  </AssignVariable>
</AssignMessage>

Exemple 2

L'exemple suivant attribue la valeur d'une ressource de spécification OpenAPI, chargée dans le dossier proxy dans le dossier oas, dans la variable de flux assigned-variable, puis définit cette valeur en tant que Payload dans le corps de la réponse :

<AssignMessage name='AM-Response'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>oas://Fulfillment.yaml</ResourceURL>
  </AssignVariable>
  <Set>
    <Payload contentType='application/yaml'>{assigned-variable}</Payload>
  </Set>
</AssignMessage>

<Template> (enfant de <AssignVariable>)

Spécifie un modèle de message. Un modèle de message vous permet d'effectuer une substitution de chaîne de variables lors de l'exécution de la règle, et de combiner des chaînes littérales avec des noms de variables placés entre accolades. De plus, les modèles de message sont compatibles avec les fonctions, telles que l'échappement et la conversion de casse.

Utilisez l'attribut ref pour spécifier une variable de flux dont la valeur est un modèle de message. Par exemple, vous pouvez stocker un modèle de message en tant qu'attribut personnalisé sur une application de développeur. Lorsque Apigee identifie l'application de développeur après avoir vérifié la clé API ou le jeton de sécurité (via une règle supplémentaire), l'élément <AssignVariable> peut utiliser le modèle de message de l'attribut personnalisé de l'application, disponible en tant que variable de flux à partir de la règle de sécurité. L'exemple suivant suppose que le modèle de message est disponible dans un attribut personnalisé appelé message_template sur l'application de développement qui effectue l'appel d'API, où la règle VerifyAPIKey a été utilisée pour valider la clé API de l'application :

<Template ref='verifyapikey.myVerifyAPIKeyPolicy.app.name.message_template'/>

Valeur par défaut	ND
Requis ?	Facultatif
Type	Chaîne
Élément parent	<AssignVariable>
Éléments enfants	Aucune

L'élément <Template> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
  </AssignVariable>
</AssignMessage>

Exemple 1

L'exemple suivant utilise la syntaxe de modélisation de messages pour concaténer deux variables de contexte avec une chaîne littérale (un trait d'union) entre elles :

<AssignMessage name='AV-via-template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

Exemple 2

L'exemple suivant spécifie une variable de flux, où la valeur de la variable est un modèle de message prédéfini. Utilisez cette option si vous souhaitez injecter un modèle prédéfini au moment de l'exécution sans avoir à modifier la stratégie :

<AssignMessage name='AV-via-template-indirectly'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_template_variable'/>
  </AssignVariable>
</AssignMessage>

Exemple 3

L'exemple suivant spécifie une variable de flux et une valeur textuelle. Dans ce cas, si la variable référencée n'est pas nulle, cette valeur est utilisée comme modèle. Si la valeur référencée est nulle, la valeur de texte (dans ce cas, {system.uuid}-{messageid}) est utilisée comme modèle. Ce modèle est utile pour fournir une valeur override, où, dans certains cas, vous souhaitez remplacer le modèle par défaut (la partie texte) par des valeurs définies de manière dynamique. Par exemple, une instruction conditionnelle peut extraire une valeur d'un mappage clé-valeur et définir la variable référencée sur cette valeur :

<AssignMessage name='AV-template-with-fallback'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Template ref='my_variable'>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

<Value> (enfant de <AssignVariable>)

Définit la valeur de la variable de flux de destination définie avec <AssignVariable>. La valeur est toujours interprétée comme une chaîne littérale. Vous ne pouvez pas utiliser une variable de flux comme valeur, même si vous la placez entre accolades ({}). Pour utiliser une variable de flux, utilisez plutôt <Ref>.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Chaîne
Élément parent	<AssignVariable>
Éléments enfants	None

Utilisé conjointement avec l'élément <Ref>, <Value> sert de valeur par défaut (ou de remplacement). Si <Ref> n'est pas spécifié, ne peut pas être résolu ou si sa valeur est nulle, la valeur de <Value> est utilisée.

L'élément <Value> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>
</AssignMessage>

Exemple 1

L'exemple suivant définit la valeur de la variable de flux de destination, myvar, sur la valeur littérale 42 :

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

Exemple 2

L'exemple suivant attribue la valeur de la variable de flux request.header.user-agent à la variable de flux myvar et la valeur du paramètre de requête country à la variable Country :

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

Si l'une des attributions échoue, <AssignVariable> attribue plutôt la valeur ErrorOnCopy à la variable de flux de destination.

<Copy>

Copie les valeurs à partir du message spécifié par l'attribut source vers le message spécifié par l'élément <AssignTo>. Si vous ne spécifiez pas de cible avec <AssignTo>, cette règle copie les valeurs dans la requête ou la réponse, selon l'emplacement du flux où cette règle s'exécute.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Chaîne
Élément parent	<AssignMessage>
Éléments enfants	<FormParams> <Headers> <Path> <Payload> <QueryParams> <StatusCode> <Verb> <Version>

Si vous ne spécifiez aucun élément enfant sous l'élément <Copy>, il copie toutes les parties du message source désigné.

L'élément <Copy> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
    <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Path>[false|true]</Path>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>
  <!-- Used as the destination for the <Copy> values -->
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>
</AssignMessage>
  

Exemple 1

L'exemple suivant copie un en-tête, trois paramètres de formulaire, le chemin d'accès et tous les paramètres de requête depuis le message request à une nouvelle requête personnalisée nommée newRequest :

<AssignMessage name="AM-copy-1">
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1"/>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1"/>
      <FormParam name="Form_Param_Name_2"/>
      <FormParam name="Form_Param_Name_3"/>
    </FormParams>
    <Path>true</Path>
    <QueryParams/>
  </Copy>
</AssignMessage>

Comme les éléments tels que <Payload> et <Verb> ne sont pas présents, la règle ne copie pas ces parties du message.

Exemple 2

L'exemple suivant supprime d'abord tout le contenu du message response existant, puis copie toutes les valeurs d'un message différent appelé secondResponse dans le message response :

<AssignMessage name='AM-Copy-Response'>
  <AssignTo createNew="false" transport="http" type="response">response</AssignTo>
  <!-- first remove any existing values -->
  <Remove/>
  <!-- then copy everything from the designated message -->
  <Copy source="secondResponse"/>
</AssignMessage>

L'élément <Copy> possède un seul attribut :

Attribut	Description	nécessaire	Type
source	Spécifie l'objet source de la copie. Si source n'est pas spécifié, la valeur par défaut sera message, qui prend une valeur différente en fonction du flux dans lequel la règle s'exécute. Si la règle s'exécute dans le flux de requête, la variable message fait référence à l'objet request. Si la règle s'exécute dans le flux de réponse, la variable message fait référence à l'objet response. Si la variable spécifiée dans l'attribut source ne peut pas être résolue, ou si elle est résolue en un type qui n'est pas un message, <Copy> n'aura aucun effet. Assurez-vous que la valeur que vous spécifiez pour source est différente du message de destination, qu'il s'agisse du message de destination par défaut ou d'une destination spécifiée explicitement avec <AssignTo>. Si le paramètre source est identique au message de destination, l'action <Copy> n'a aucun effet.	Facultatif	Chaîne

<FormParams> (enfant de <Copy>)

Copie les paramètres de formulaire de la requête spécifiée par l'attribut source de l'élément <Copy> vers la requête spécifiée par <AssignTo>. Cet élément n'a aucun effet sur une réponse.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <FormParam> ou tableau vide
Élément parent	<Copy>
Éléments enfants	<FormParam>

L'élément <FormParams> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  </Copy>
</AssignMessage>

Exemple 1

L'exemple suivant copie un seul paramètre de formulaire de la requête vers la requête personnalisée MyCustomRequest :

<AssignMessage name="copy-formparams-1">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName">Form param value 1</FormParam>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemple 2

L'exemple suivant copie tous les paramètres de formulaire dans la requête personnalisée MyCustomRequest :

<AssignMessage name="copy-formparams-2">
  <Copy source="request">
    <FormParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemple 3

L'exemple suivant copie trois paramètres de formulaire dans la requête personnalisée MyCustomRequest :

<AssignMessage name="copy-formparams-3">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName1"/>
      <FormParam name="paramName2"/>
      <FormParam name="paramName3"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemple 4

S'il existe plusieurs paramètres de formulaire du même nom, utilisez la syntaxe suivante :

<AssignMessage name="copy-formparams-4">
  <Copy source="request">
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Cet exemple copie f1, f2 et la deuxième valeur de f3. Si f3 n'a qu'une seule valeur, le paramètre n'est pas copié.

Vous ne pouvez utiliser <FormParams> que si les critères suivants sont remplis :

• Verbe HTTP : POST
• Type de message : réponse
• Un des éléments suivants (ou les deux) :
  • Données de formulaire : défini sur une valeur ou sur "" (la chaîne vide). Par exemple, avec curl, ajoutez -d "" à votre requête.
  • En-tête Content-Length :défini sur 0 (si aucune donnée ne figure dans la requête d'origine, sinon, la longueur actuelle). Par exemple, avec curl, ajoutez -H "Content-Length: 0" à votre requête.

Lorsque vous copiez <FormParams>, <Copy> définit la valeur Content-Type du message sur application/x-www-form-urlencoded avant de l'envoyer au service cible.

<Headers> (enfant de <Copy>)

Copie les en-têtes HTTP à partir du message de requête ou de réponse spécifié par l'attribut source de l'élément <Copy> vers le message de requête ou de réponse spécifié par l'élément <AssignTo>.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <Header> ou tableau vide
Élément parent	<Copy>
Éléments enfants	<Header>

L'élément <Headers> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
  </Copy>
</AssignMessage>

Exemple 1

L'exemple suivant copie l'en-tête user-agent de la requête dans le nouvel objet de requête personnalisé :

<AssignMessage name="AM-copy-headers-1">
  <Copy source="request">
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemple 2

Pour copier tous les en-têtes, utilisez un élément <Headers> vide, comme le montre l'exemple suivant :

<AssignMessage name="copy-headers-2">
  <Copy source="request">
    <Headers/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemple 3

Si plusieurs en-têtes portent le même nom, utilisez la syntaxe suivante :

<AssignMessage name="copy-headers-3">
  <Copy source="request">
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Cet exemple copie h1, h2 et la deuxième valeur de h3. Si h3 n'a qu'une seule valeur, il n'est pas copié.

<Path> (enfant de <Copy>)

Détermine si le chemin d'accès doit être copié de la requête source vers la requête de destination. Cet élément n'a aucun effet sur une réponse.

Si la valeur est true, cette règle copie le chemin d'accès à partir du message de requête spécifié par l'attribut source de l'élément <Copy> dans le message de requête spécifié par l'élément <AssignTo>.

Valeur par défaut	Faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<Copy>
Éléments enfants	Aucune

L'élément <Path> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Path>[false|true]</Path>
  </Copy>
</AssignMessage>

Exemple 1

L'exemple suivant indique que la règle AssignMessage doit copier le chemin d'accès de la requête source vers le nouvel objet de requête personnalisé :

<AssignMessage name="copy-path-1">
  <Copy source="request">
    <Path>true</Path>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Vous ne pouvez utiliser <Path> que si les critères suivants sont remplis :

• Type de message : Requête

<Payload> (enfant de <Copy>)

Détermine si la charge utile doit être copiée depuis la source vers la destination. La source et la destination peuvent être des requêtes ou des réponses.

Si la valeur est true, cette règle copie la charge utile à partir du message spécifié par l'attribut source de l'élément <Copy> dans le message spécifié par l'élément <AssignTo>.

Valeur par défaut	Faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<Copy>
Éléments enfants	Aucune

L'élément <Payload> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>

Exemple 1

L'exemple suivant définit <Payload> sur true afin que la charge utile de la requête soit copiée de la requête dans la réponse :

<AssignMessage name="AM-copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>

<QueryParams> (enfant de <Copy>)

Copie les paramètres de chaîne de requête depuis la requête spécifiée par l'attribut source de l'élément <Copy> vers la requête spécifiée par l'élément <AssignTo>. Cet élément n'a aucun effet sur une réponse.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <QueryParam> ou tableau vide
Élément parent	<QueryParam>
Éléments enfants	Aucune

L'élément <QueryParams> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Copy>
</AssignMessage>

Exemple 1

L'exemple suivant copie le paramètre de requête my_param de la requête dans un nouvel objet de requête personnalisé :

<AssignMessage name="copy-queryparams-1">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="my_param"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemple 2

L'exemple suivant copie tous les paramètres de requête depuis la requête vers un nouvel objet de requête personnalisé :

<AssignMessage name="copy-queryparams-2">
  <Copy source="request">
    <QueryParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemple 3

S'il existe plusieurs paramètres de requête portant le même nom, utilisez la syntaxe suivante 

<AssignMessage name="copy-queryparams-3">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="qp1"/>
      <QueryParam name="qp2"/>
      <QueryParam name="qp3.2"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Cet exemple copie qp1, qp2 et la deuxième valeur de qp3. Si qp3 ne comporte qu'une seule valeur, le paramètre n'est pas copié.

Vous ne pouvez utiliser <QueryParams> que lorsque les critères suivants sont remplis :

• Verbes HTTP : GET, POST, PATCH, DELETE
• Type de message : Requête

<StatusCode> (enfant de <Copy>)

Détermine si le code d'état est copié de la réponse source vers la réponse de destination. Cet élément n'a aucun effet sur une requête.

Si la valeur est true, cette règle copie le code d'état à partir du message de réponse spécifié par l'attribut source de l'élément <Copy> dans le message de réponse spécifié par l'élément <AssignTo>.

Valeur par défaut	Faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<Copy>
Éléments enfants	Aucune

L'élément <StatusCode> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <StatusCode>[false|true]</StatusCode>
  </Copy>
</AssignMessage>

Exemple 1

L'exemple suivant définit <StatusCode> sur true, qui copie le code d'état de l'objet de réponse par défaut dans un nouvel objet de réponse personnalisé :

<AssignMessage name="copy-statuscode-1">
  <Copy source="response">
    <StatusCode>true</StatusCode>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response">MyCustomResponse</AssignTo>
</AssignMessage>

Vous ne pouvez utiliser <StatusCode> que lorsque les messages source et de destination sont de type Response.

Une utilisation courante de <StatusCode> consiste à définir une valeur de code d'état de la réponse du proxy différente de celle reçue de la cible.

<Verb> (enfant de <Copy>)

Détermine si le verbe HTTP est copié depuis la requête source vers la requête de destination. Cet élément n'a aucun effet sur une réponse.

Si la valeur est true, copie le verbe trouvé dans l'attribut source de l'élément <Copy> dans la requête spécifiée dans l'élément <AssignTo>.

Valeur par défaut	Faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<Copy>
Éléments enfants	Aucune

L'élément <Verb> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Verb>[false|true]</Verb>
  </Copy>
</AssignMessage>

Exemple 1

L'exemple suivant définit <Verb> sur true, qui copie le verbe de la requête par défaut dans une nouvelle requête personnalisée :

<AssignMessage name="copy-verb-1">
  <Copy source="request">
    <Verb>true</Verb>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Vous ne pouvez utiliser <Verb> que si les critères suivants sont remplis :

• Type de message : Requête

<Version> (enfant de <Copy>)

Détermine si la version HTTP est copiée de la requête source vers la requête de destination. Cet élément n'a aucun effet sur une réponse.

Si la valeur est true, copie la version HTTP trouvée dans l'attribut source de l'élément <Copy> dans l'objet spécifié par l'élément <AssignTo>.

Valeur par défaut	Faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<Copy>
Éléments enfants	Aucune

L'élément <Version> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Version>[false|true]</Version>
  </Copy>
</AssignMessage>

Exemple 1

L'exemple suivant définit <Version> sur true sur la requête, qui copie la version de l'objet de requête par défaut dans un nouvel objet de requête personnalisé :

<AssignMessage name="copy-version-1">
  <Copy source="request">
    <Version>true</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Vous ne pouvez utiliser <Version> que si les critères suivants sont remplis :

• Type de message : Requête

<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 et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut	ND
Obligatoire ?	Facultatif. Si vous omettez <DisplayName>, la valeur de l'attribut name de la règle est utilisée.
Type	Chaîne
Élément parent	<PolicyElement>
Éléments enfants	Aucune

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Exemple

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<IgnoreUnresolvedVariables>

Détermine si le traitement s'arrête lorsqu'une variable non résolue est rencontrée.

Valeur par défaut	Faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<AssignMessage>
Éléments enfants	Aucun

Définissez la valeur sur true pour ignorer les variables non résolues et poursuivre le traitement, sinon false. La valeur par défaut est false.

Définir l'élément <IgnoreUnresolvedVariables> sur true n'a pas le même objet que définir l'élément continueOnError de <AssignMessage> sur true car il est spécifique à la définition et à l'obtention de valeurs de variables. Si vous définissez continueOnError sur true, Apigee ignore toutes les erreurs, pas seulement celles rencontrées lors de l'utilisation de variables.

L'élément <IgnoreUnresolvedVariables> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</AssignMessage>

Exemple 1

L'exemple suivant définit <IgnoreUnresolvedVariables> sur true :

<AssignMessage name="AM-Set-Headers">
  <Set>
    <Headers>
      <Header name='new-header'>{possibly-defined-variable}<Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Comme <IgnoreUnresolvedVariables> est défini sur true, si la variable possibly-defined-variable n'est pas définie, cette règle ne génère pas d'erreur.

<Remove>

Supprime les en-têtes, les paramètres de requête, les paramètres de formulaire et/ou la charge utile d'un message. Une balise <Remove> vide supprime tout le contenu du message.

Le message affecté peut être une requête ou une réponse. Vous pouvez spécifier le message sur lequel agit <Remove> en utilisant l'élément <AssignTo>.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Type complexe
Élément parent	<AssignMessage>
Éléments enfants	<FormParams> <Headers> <Payload> <QueryParams>

Un cas d'utilisation courant de <Remove> consiste à supprimer un paramètre de requête ou un en-tête contenant des informations sensibles de l'objet de requête entrant afin d'éviter de le transmettre au serveur backend.

L'élément <Remove> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

Exemple 1

L'exemple suivant supprime le corps du message de la réponse :

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

Dans le flux de réponse, cette stratégie supprime le corps de la réponse, ne renvoyant que les en-têtes HTTP au client.

Exemple 2

L'exemple suivant supprime tous les paramètres de formulaire et un paramètre de requête de l'objet request :

<AssignMessage name="AM-remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 3

L'exemple suivant supprime tout d'un objet de message :

<AssignMessage name="AM-remove-3">
  <Remove/>
  <AssignTo>request</AssignTo>
</AssignMessage>

En règle générale, vous ne devez effectuer cette opération que si vous utilisez les éléments <Set> ou <Copy> pour définir des valeurs de remplacement dans le message.

<FormParams> (enfant de <Remove>)

Supprime les paramètres de formulaire spécifiés de la requête. Cet élément n'a aucun effet sur une réponse.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <FormParam> ou tableau vide
Élément parent	<Remove>
Éléments enfants	<FormParam>

L'élément <FormParams> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
  </Remove>
</AssignMessage>

Exemple 1

L'exemple suivant supprime trois paramètres de formulaire de la requête :

<AssignMessage name="AM-remove-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 2

L'exemple suivant supprime tous les paramètres de formulaire de la requête :

<AssignMessage name="AM-remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 3

S'il existe plusieurs paramètres de formulaire du même nom, utilisez la syntaxe suivante :

<AssignMessage name="AM-remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Cet exemple supprime f1, f2 et la deuxième valeur de f3. Si f3 n'a qu'une seule valeur, le paramètre n'est pas supprimé.

Vous ne pouvez utiliser <FormParams> que si les critères suivants sont remplis :

• Type de message : Requête
• Content-Type : application/x-www-form-urlencoded

<Headers> (enfant de <Remove>)

Supprime les en-têtes HTTP spécifiés de la requête ou de la réponse, indiquée par l'élément <AssignTo>.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <Header> ou tableau vide
Élément parent	<Remove>
Éléments enfants	<Header>

L'élément <Headers> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
  </Remove>
</AssignMessage>

Exemple 1

L'exemple suivant supprime l'en-tête user-agent de la requête :

<AssignMessage name="AM-remove-one-header">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 2

L'exemple suivant supprime tous les en-têtes de la requête :

<AssignMessage name="AM-remove-all-headers">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 3

Si plusieurs en-têtes portent le même nom, utilisez la syntaxe suivante :

<AssignMessage name="AM-remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Cet exemple supprime h1, h2 et la deuxième valeur de h3 de la requête. Si h3 n'a qu'une seule valeur, le paramètre n'est pas supprimé.

<Payload> (enfant de <Remove>)

Détermine si <Remove> supprime la charge utile dans la requête ou la réponse, spécifiée par l'élément <AssignTo>. Définissez la valeur sur true pour effacer la charge utile, sinon false. La valeur par défaut est false.

Valeur par défaut	Faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<Remove>
Éléments enfants	Aucune

L'élément <Payload> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <Payload>[false|true]</Payload>
  </Remove>
</AssignMessage>

Exemple 1

L'exemple suivant définit <Payload> sur true afin que la charge utile de la requête soit effacée :

<AssignMessage name="AM-remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

<QueryParams> (enfant de <Remove>)

Supprime les paramètres de requête spécifiés de la requête. Cet élément n'a aucun effet sur une réponse.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <QueryParam> ou tableau vide
Élément parent	<Remove>
Éléments enfants	<QueryParam>

L'élément <QueryParams> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

Exemple 1

L'exemple suivant permet de supprimer un seul paramètre de requête de la requête :

<AssignMessage name="AM-remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 2

L'exemple suivant supprime tous les paramètres de la requête :

<AssignMessage name="AM-remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 3

S'il existe plusieurs paramètres de requête portant le même nom, utilisez la syntaxe suivante 

<AssignMessage name="AM-remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Cet exemple supprime qp1, qp2 et la deuxième valeur de qp3 de la requête. Si qp3 n'a qu'une seule valeur, le paramètre n'est pas supprimé.

Exemple 4

L'exemple suivant supprime le paramètre de requête apikey de la requête :

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Vous ne pouvez utiliser <QueryParams> que lorsque les critères suivants sont remplis :

• Verbes HTTP : GET, POST, PATCH, DELETE
• Type de message : Requête

<Set>

Définit les informations dans le message de requête ou de réponse, spécifié par l'élément <AssignTo>. <Set> écrase les en-têtes ou les paramètres de requête ou de formulaire qui existent déjà dans le message d'origine, ou en ajoute de nouveaux.

Les en-têtes et les paramètres de requête et de formulaire dans un message HTTP peuvent contenir plusieurs valeurs. Pour ajouter des valeurs supplémentaires à un en-tête ou à un paramètre, utilisez plutôt l'élément <Add>.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Type complexe
Élément parent	<AssignMessage>
Éléments enfants	<FormParams> <Headers> <Payload> <Path> <QueryParams> <StatusCode> <Verb> <Version>

Remarque : Les sous-éléments de <Set> sont compatibles avec la fonctionnalité de substitution de chaîne dynamique appelée modélisation de message.

L'élément <Set> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <Path>PATH</Path>
    <Payload contentType="CONTENT_TYPE" variablePrefix="PREFIX"
        variableSuffix="SUFFIX">NEW_PAYLOAD</Payload>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
    <StatusCode>HTTP_STATUS_CODE or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

Exemple 1

L'exemple suivant définit un en-tête spécifique. Lorsque cette règle est associée dans le flux de requête, elle permet au système en amont de recevoir un en-tête supplémentaire qui n'a pas été inclus dans la requête entrante d'origine.

<AssignMessage name="AM-Set-Header">
  <Set>
    <Headers>
        <Header name="authenticated-developer">{verifyapikey.VAK-1.developer.id}</Header>
    </Headers>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 2

L'exemple suivant écrase la charge utile d'une réponse, ainsi que l'en-tête Content-Type.

<AssignMessage name="AM-Overwrite-Payload">
  <Set>
    <Payload contentType="application/json">{ "status" : 42 }</Payload>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

<FormParams> (enfant de <Set>)

Remplace les paramètres de formulaire existants sur une requête et les remplace par les nouvelles valeurs que vous spécifiez avec cet élément. Cet élément n'a aucun effet sur une réponse.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <FormParam>
Élément parent	<Set>
Éléments enfants	<FormParam>

L'élément <FormParams> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  </Set>
</AssignMessage>

Exemple 1

L'exemple suivant définit un paramètre de formulaire appelé myparam sur la valeur de la variable request.header.myparam dans une nouvelle requête personnalisée :

<AssignMessage name="AM-set-formparams-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
  </Set>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Vous ne pouvez utiliser <FormParams> que si les critères suivants sont remplis :

• Verbe HTTP : POST
• Type de message : Requête

Si vous définissez des paramètres de formulaire vides dans votre règle (<Add><FormParams/></Add>), celle-ci n'ajoute aucun paramètre de formulaire. Cela revient à omettre le paramètre <FormParams>.

<Set> remplace la variable Content-Type du message par application/x-www-form-urlencoded avant de l'envoyer au point de terminaison cible.

<Headers> (enfant de <Set>)

Remplace les en-têtes HTTP existants dans la requête ou la réponse, qui est spécifiée par l'élément <AssignTo>.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <Header>
Élément parent	<Set>
Éléments enfants	<Header>

L'élément <Headers> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
  </Set>
</AssignMessage>

Exemple 1

L'exemple suivant définit l'en-tête x-ratelimit-remaining sur la valeur de la variable ratelimit.Quota-1.available.count :

<AssignMessage name="AM-Set-RateLimit-Header">
  <Set>
    <Headers>
      <Header name="X-RateLimit-Remaining">{ratelimit.Quota-1.available.count}</Header>
    </Headers>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

Si vous définissez des en-têtes vides dans votre stratégie (<Set><Headers/></Set>), la règle ne définit aucun en-tête. Cela aura le même effet que d'omettre <Headers>.

<Path> (enfant de <Set>)

Remarque :

Cet élément ne fonctionne pas comme prévu pour remplacer/réécrire l'URL cible d'un proxy. (Il permet de définir le chemin d'accès dans les ServiceCallout, comme illustré dans l'exemple pratique ci-dessous.)

Parfois, vous devrez peut-être envoyer un message à une URL autre que l'URL définie dans une requête TargetEndpoint d'un proxy d'API. Si vous souhaitez réécrire l'URL cible, remplacez la variable target.url dans le fichier TargetEndpoint à l'aide de l'élément <AssignVariable>. (Vous ne pouvez pas remplacer target.url dans le fichier ProxyEndpoint, car Apigee définit la variable dans TargetEndpoint).

L'exemple suivant montre comment une règle AssignMessage remplace target.url. Ici aussi, ajoutez la règle à la requête TargetEndpoint. Avec cette règle, le proxy appelle l'URL ci-dessous à la place de l'URL définie dans la requête TargetEndpoint.

<AssignMessage name="Assign-Message-1">
...
  <AssignVariable>
    <Name>target.url</Name>
    <Value>http://mocktarget.apigee.net/user?user=Dude</Value>
  </AssignVariable>
...

Vous pouvez également utiliser une règle JavaScript dans la requête TargetEndpoint pour remplacer target.url.

<Payload> (enfant de <Set>)

Définit le corps du message pour une requête ou une réponse, spécifiée par l'élément <AssignTo>. La charge utile peut être n'importe quel type de contenu valide, tel que du texte brut, JSON ou XML.

Valeur par défaut	Chaîne vide
Obligatoire ?	Facultatif
Type	Chaîne
Élément parent	<Set>
Éléments enfants	Aucune

L'élément <Payload> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Payload contentType="CONTENT_TYPE" variablePrefix="PREFIX"
        variableSuffix="SUFFIX">NEW_PAYLOAD</Payload>
  </Set>
</AssignMessage>

Exemple 1

L'exemple suivant définit une charge utile en texte brut :

<AssignMessage name="set-payload-1">
  <Set>
    <Payload contentType="text/plain">42</Payload>
  </Set>
</AssignMessage>

Exemple 2

L'exemple suivant définit une charge utile JSON :

<AssignMessage name="set-payload-2">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"bar"}
    </Payload>
  </Set>
</AssignMessage>

Exemple 3

L'exemple suivant insère des valeurs de variables dans la charge utile en plaçant les noms de variables entre accolades :

<AssignMessage name="set-payload-3">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"{variable_name}"}
    </Payload>
  </Set>
</AssignMessage>

Dans les anciennes versions d'Apigee, par exemple avant la version du cloud 16.08.17, vous ne pouviez pas utiliser les accolades pour désigner des références de variables dans les charges utiles JSON. Dans ces versions, vous deviez utiliser les attributs variablePrefix et variableSuffix pour spécifier des caractères de délimitation, et les utiliser pour encapsuler les noms de variables, comme ceci :

<AssignMessage name="set-payload-3b">
  <Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
      {"name":"foo", "type":"@variable_name#"}
    </Payload>
  </Set>
</AssignMessage>

Cette ancienne syntaxe fonctionne toujours.

Exemple 4

Le contenu de <Payload> est traité comme un modèle de message. Cela signifie que la règle AssignMessage remplace les variables placées entre accolades par la valeur des variables référencées lors de l'exécution.

L'exemple suivant utilise la syntaxe avec accolades pour définir une partie de la charge utile sur une valeur de variable :

<AssignMessage name="set-payload-4">
  <Set>
    <Payload contentType="text/xml">
      <root>
        <e1>sunday</e1>
        <e2>funday</e2>
        <e3>{var1}</e3>
      </root>
    </Payload>
  </Set>
</AssignMessage>

Remarque : N'incluez pas le profil XML dans la charge utile, sinon, vous obtiendrez des erreurs de validation XML.

Le tableau suivant décrit les attributs de <Payload> :

Attribut	Description	Présence	Type
contentType	Si elle est spécifiée, la valeur de contentType est attribuée à l'en-tête HTTP Content-Type.	Facultatif	Chaîne
variablePrefix	Spécifie éventuellement le délimiteur de début sur une variable de flux. La valeur par défaut est "{". Pour en savoir plus, consultez la documentation de référence sur les variables de flux.	Facultatif	Caractère
variableSuffix	Spécifie éventuellement le délimiteur final à une variable de flux. La valeur par défaut est "}". Pour plus d'informations, consultez la documentation de référence sur les variables de flux.	Facultatif	Caractère

<QueryParams> (enfant de <Set>)

Remplace les paramètres de requête existants dans la requête par de nouvelles valeurs. Cet élément n'a aucun effet sur une réponse.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Tableau d'éléments <QueryParam>
Élément parent	<Set>
Éléments enfants	<QueryParam>

L'élément <QueryParams> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Set>
</AssignMessage>

Exemple 1

L'exemple suivant définit le paramètre de requête address sur la valeur de la variable request.header.address :

<AssignMessage name="AM-set-queryparams-1">
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

Vous ne pouvez utiliser <QueryParams> que lorsque les critères suivants sont remplis :

• Verbes HTTP : GET, POST, PATCH, DELETE
• Type de message : Requête

Si vous définissez des paramètres de requête vides dans votre règle (<Set><QueryParams/></Set>), celle-ci ne définit aucun paramètre de requête. Cela revient à omettre <QueryParams>.

<StatusCode> (enfant de <Set>)

Définit le code d'état sur la réponse. Cet élément n'a aucun effet sur une requête.

Valeur par défaut	'200' (lorsque l'attribut createNew de l'élément <AssignTo> est défini sur "true")
Obligatoire ?	Facultatif
Type	Chaîne ou VARIABLE
Élément parent	<Set>
Éléments enfants	Aucune

L'élément <StatusCode> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <StatusCode>HTTP_STATUS_CODE or {variable}</StatusCode>
  </Set>
</AssignMessage>

Exemple 1

L'exemple suivant définit un code d'état simple :

<AssignMessage name="AM-set-statuscode-404">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

Exemple 2

Le contenu de <StatusCode> est traité comme un modèle de message. Cela signifie qu'un nom de variable placé entre accolades est remplacé par la valeur de la variable référencée lors de l'exécution, comme illustré dans l'exemple suivant :

<AssignMessage name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

Vous ne pouvez utiliser <StatusCode> que lorsque les critères suivants sont remplis :

• Type de message : réponse

<Verb> (enfant de <Set>)

Définit le verbe HTTP sur la requête. Cet élément n'a aucun effet sur une réponse.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Chaîne ou VARIABLE
Élément parent	<Set>
Éléments enfants	Aucune

L'élément <Verb> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
  </Set>
</AssignMessage>

Exemple 1

L'exemple suivant définit un verbe simple sur la requête :

<AssignMessage name="AM-set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemple 2

Le contenu de <Verb> est traité comme un modèle de message. Cela signifie qu'un nom de variable placé entre accolades sera remplacé au moment de l'exécution par la valeur de la variable référencée.

L'exemple suivant utilise une variable pour renseigner un verbe :

<AssignMessage name="AM-set-verb-to-dynamic-value">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

Vous ne pouvez utiliser <Verb> que lorsque les critères suivants sont remplis :

• Type de message : Requête

<Version> (enfant de <Set>)

Définit la version HTTP sur une requête. Cet élément n'a aucun effet sur une réponse.

Valeur par défaut	ND
Requis ?	Facultatif
Type	Chaîne ou VARIABLE
Élément parent	<Set>
Éléments enfants	Aucune

L'élément <Version> utilise la syntaxe suivante :

Syntaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

Exemple 1

L'exemple suivant définit le numéro de version sur 1.1 :

<AssignMessage name="AM-set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
 </AssignMessage>

Exemple 2

La variable suivante utilise une variable entre accolades pour définir le numéro de version :

<AssignMessage name="AM-set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

Le contenu de <Version> est traité comme un modèle de message. Cela signifie qu'un nom de variable placé entre accolades sera remplacé lors de l'exécution par la valeur de la variable référencée.

Vous ne pouvez utiliser <Version> que lorsque les critères suivants sont remplis :

• Type de message : Requête

Créer des messages de requête personnalisés

La règle AssignMessage vous permet de créer un message de requête personnalisé. Après avoir créé une requête personnalisée, vous pouvez l'utiliser de la manière suivante :

• Accéder à ses variables dans d'autres règles
• La transmettre à un service externe

Remarque : Vous ne pouvez pas transmettre un message de requête personnalisé au point de terminaison cible du flux. Apigee ne transmet que la requête d'origine (avec toutes les modifications apportées) au point de terminaison cible.

Pour créer un message de requête personnalisé, utilisez l'élément <AssignTo> dans votre règle AssignMessage. Définissez createNew sur true et spécifiez le nom du nouveau message dans le corps de l'élément, comme le montre l'exemple suivant :

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request">MyRequestObject</AssignTo>
  ...
</AssignMessage>

Par défaut, Apigee n'effectue aucune action par rapport au message de requête personnalisé. Une fois créé, Apigee poursuit le flux avec la requête d'origine. Pour utiliser la requête personnalisée, ajoutez à votre proxy une règle telle que la règle ServiceCallout, puis référencez explicitement le message de requête nouvellement créé dans la configuration de cette règle. Cela vous permet de transmettre la requête personnalisée à un point de terminaison de service externe.

Les exemples suivants créent des messages de requête personnalisés :

Exemple 1

L'exemple suivant crée un objet de requête personnalisé avec la règle AssignMessage :

<AssignMessage name="AssignMessage-3">
  <AssignTo createNew="true" type="request">MyCustomRequest</AssignTo>
  <Copy>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Copy>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.addy}</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Cet exemple :

• Crée un objet de message de requête appelé MyCustomRequest.
• Sur MyCustomRequest, cette règle :
  • Copie la valeur de l'en-tête HTTP user-agent depuis la requête entrante vers le nouveau message. Comme <Copy> ne spécifie pas l'attribut source, Apigee utilise le message request comme source à partir de laquelle copier.
  • Définit le paramètre de requête address du message personnalisé sur la valeur du paramètre de requête addy de la requête entrante.
  • Définit le verbe HTTP sur GET.
• Définit <IgnoreUnresolvedVariables> sur false. Lorsque la valeur de <IgnoreUnresolvedVariables> est false, si l'une des variables référencées dans la configuration de la règle n'existe pas, Apigee entre dans l'état d'erreur dans le flux d'API.

Exemple 2

Voici un autre exemple illustrant la création d'un objet de requête personnalisé avec la règle AssignMessage :

<AssignMessage name="AssignMessage-2">
  <AssignTo createNew="true" type="request">partner.request</AssignTo>
  <Set>
    <Verb>POST</Verb>
    <Payload contentType="text/xml">
      <request><operation>105</operation></request>
    </Payload>
  </Set>
</AssignMessage>

Cet exemple crée une requête personnalisée appelée partner.request. Il définit ensuite <Verb> et <Payload> sur la nouvelle requête.

Vous pouvez accéder aux différentes propriétés d'un message personnalisé dans une autre règle AssignMessage qui se produit ultérieurement dans le flux. L'exemple suivant récupère la valeur d'un en-tête à partir d'une réponse personnalisée nommée et la place dans un nouvel en-tête du message de requête :

<AssignMessage name="AM-Copy-Custom-Header">
  <AssignTo>request</AssignTo>
  <Set>
    <Headers>
      <Header name="injected-approval-id">{MyCalloutResponse.header.approval-id}</Header>
    </Headers>
  </Set>
</AssignMessage>

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.assignmessage.SetVariableFailed	500	La règle n'a pas pu définir de variable. Consultez la chaîne d'erreur pour le nom de la variable non résolue.
steps.assignmessage.VariableOfNonMsgType	500	Cette erreur se produit si l'attribut source de l'élément <Copy> est défini sur une variable qui n'est pas de type Message. Les variables de type Message représentent des requêtes et des réponses HTTP entières. Les variables de flux Apigee intégrées request, response et message sont de type Message. Pour en savoir plus sur les variables de message, consultez la documentation de référence sur les variables.
steps.assignmessage.UnresolvedVariable	500	Cette erreur se produit si une variable spécifiée dans la règle AssignMessage est : est hors de portée (non disponible dans le flux spécifique où la stratégie est exécutée) ou impossible à résoudre (non définie)

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
InvalidIndex	Si l'index spécifié dans les éléments <Copy> et/ou <Remove> de la règle AssignMessage est 0 ou un nombre négatif, le déploiement du proxy d'API échoue.
InvalidVariableName	Si l'élément enfant <Name> est vide ou non spécifié dans l'élément <AssignVariable>, le déploiement du proxy d'API échoue, car il n'existe pas de nom de variable valide auquel attribuer une valeur. Vous devez indiquer un nom de variable valide.
InvalidPayload	Une charge utile spécifiée dans la règle n'est pas valide.

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 "UnresolvedVariable"
assignmessage.POLICY_NAME.failed	POLICY_NAME est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur.	assignmessage.AM-SetResponse.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":{  
      "detail":{  
         "errorcode":"steps.assignmessage.VariableOfNonMsgType"
      },
      "faultstring":"AssignMessage[AM-SetResponse]: value of variable is not of type Message"
   }
}

Exemple de règle de défaillance

<FaultRule name="Assign Message Faults">
    <Step>
        <Name>AM-CustomNonMessageTypeErrorResponse</Name>
        <Condition>(fault.name Matches "VariableOfNonMsgType") </Condition>
    </Step>
    <Step>
        <Name>AM-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(assignmessage.failed = true) </Condition>
</FaultRule>

Schémas

Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.

Articles associés

Des exemples fonctionnels de la règle AssignMessage sont disponibles dans les exemples de la plate-forme d'API.

Pour obtenir un exemple plus détaillé sur la manière de remplacer target.url dans ProxyEndpoint, consultez cet article de la communauté Apigee.

Pour voir un chemin d'accès en action dans une règle ServiceCallout, consultez cet exemple pratique dans les exemples Apigee sur GitHub. Il vous suffit de cloner le dépôt et de suivre les instructions de cet article. L'exemple utilise la règle AssignMessage pour définir un chemin de requête, puis une règle ServiceCallout pour envoyer la requête à un service externe.