Tutoriel
Ce tutoriel et les exemples montrent l’utilisation de fragments de code VCL personnalisés standard avec les dictionnaires Edge et les listes de contrôle d’accès Edge pour personnaliser la configuration de service Fastly pour Adobe Commerce. Pour plus d’informations, voir la documentation Fastly :
- Guide de Fastly VCL : Informations sur l’implémentation de Fastly Varnish, les extensions de Fastly VCL et les ressources permettant d’en savoir plus sur le vernis et le VCL.
- Référence Fastly VCL : référence de programmation détaillée pour développer et dépanner les fragments de code VCL et VCL personnalisés Fastly.
Vous pouvez créer et gérer des fragments de code VCL personnalisés à partir de l’administration Adobe Commerce ou à l’aide de l’API Fastly :
-
Administrateur Adobe Commerce—Nous vous recommandons d’utiliser l’administrateur Adobe Commerce pour gérer les fragments de code VCL personnalisés, car cela automatise le processus de validation, de chargement et d’application des modifications VCL à la configuration de service Fastly. Vous pouvez également afficher et modifier les fragments de code VCL personnalisés ajoutés à la configuration du service Fastly à partir de l’administrateur.
-
API Fastly : si vous ne pouvez pas accéder à l’administration, utilisez l’API Fastly pour gérer les fragments de code VCL personnalisés. Par exemple, utilisez l’API pour résoudre les problèmes de configuration du service Fastly lorsque le site est hors service ou pour ajouter un fragment de code VCL personnalisé. En outre, certaines opérations ne peuvent être effectuées qu’à l’aide de l’API . Par exemple, vous devez utiliser l'API pour réactiver une ancienne version de VCL ou pour afficher tous les fragments de code VCL inclus dans une version de VCL spécifiée. Voir Référence rapide de l’API pour les fragments de code VCL.
Exemple de code de fragment de code VCL
L’exemple suivant illustre le fragment de code VCL personnalisé (format JSON) qui filtre le trafic par adresse IP client :
{
"service_id": "FASTLY_SERVICE_ID",
"version": "{Editable Version #}",
"name": "apply_acl",
"priority": "100",
"dynamic": "1",
"type": "hit",
"content": "if ((client.ip ~ {ACLNAME}) && !req.http.Fastly-FF){ error 403; }"
}
La logique VCL du champ content
effectue les actions suivantes :
-
Vérifie l’adresse IP entrante,
client.ip
à chaque requête -
Bloque toute requête avec une adresse IP incluse dans la liste de contrôle d’accès Edge ACLNAME, renvoyant une erreur
403 Forbidden
Le tableau suivant fournit des détails sur les données clés pour les fragments de code VCL personnalisés. Pour une référence plus détaillée, reportez-vous à la référence Fragments de code VCL dans la documentation Fastly .
Valeur | Description |
---|---|
API_KEY | La clé API pour accéder à votre compte Fastly. Voir Obtenir des informations d’identification. |
active | Statut actif du fragment de code ou de la version. Renvoie true ou false . Si la valeur est true, le fragment de code ou la version est en cours d’utilisation. Clonez un fragment de code actif à l’aide de son numéro de version. |
content | Fragment de code VCL à exécuter. Fastly ne prend pas en charge toutes les fonctionnalités de langage VCL. En outre, Fastly fournit des extensions avec des fonctionnalités personnalisées. Pour plus d’informations sur les fonctionnalités prises en charge, consultez la référence de programmation Fastly VCL. |
dynamic | Statut dynamique d’un fragment de code. Renvoie false pour les fragments de code standard inclus dans le VCL avec version pour la configuration de service Fastly. Renvoie true pour un fragment de code dynamique qui peut être modifié et déployé sans nécessiter une nouvelle version de VCL. |
number | Numéro de version VCL où le fragment de code est inclus. Fastly utilise Version modifiable # dans ses exemples de valeurs. Si vous ajoutez des fragments de code personnalisés à partir de l’API, incluez le numéro de version dans la requête API. Si vous ajoutez un VCL personnalisé à partir de l’administrateur, la version vous est fournie. |
priority |
Valeur numérique de Tout fragment de code VCL personnalisé avec une valeur de priorité de Tous les fragments de code VCL par défaut inclus dans le module Magento-Fastly ont
|
service_id | Identifiant de service Fastly pour un environnement d’évaluation ou de production spécifique. Cet identifiant est attribué lorsque votre projet est ajouté à l’infrastructure cloud d’Adobe Commerce compte de service Fastly. |
type | Indique l’emplacement d’insertion du fragment de code généré, tel que init (au-dessus des sous-routines) et recv (dans les sous-routines). Pour plus d’informations, consultez la référence Fastly fragments de code VCL. |
Gérer le VCL personnalisé à partir de l’administrateur
Vous pouvez ajouter des fragments de code VCL personnalisés à partir de la section Configuration Fastly > Fragments de code VCL personnalisés dans Admin.
La vue Fragments de code VCL personnalisés affiche uniquement les fragments de code qui ont été ajoutés par l’intermédiaire de l’administrateur. Si des fragments de code sont ajoutés à l’aide de l’API Fastly, utilisez l’API pour les gérer.
Les exemples suivants montrent comment créer et gérer des fragments de code VCL personnalisés à partir de l’administration, et utiliser les modules Fastly Edge et les dictionnaires Edge :
Gérer le VCL à l’aide de l’API
La présentation suivante vous explique comment créer des fichiers de fragment de code VCL standard et les ajouter à votre configuration de service Fastly à l’aide de l’API Fastly. Vous pouvez créer et gérer les fragments de code à partir de l’application terminal. Vous n’avez pas besoin d’une connexion SSH dans un environnement spécifique.
Conditions préalables :
-
Configurez votre environnement Adobe Commerce sur l’infrastructure cloud pour les services Fastly . Voir Configuration rapide.
-
Obtenez les informations d’identification de l’API Fastly pour authentifier les requêtes auprès de l’API Fastly. Assurez-vous d’obtenir les informations d’identification pour l’environnement approprié : évaluation ou production.
-
Enregistrez les informations d’identification de service Fastly en tant que variables d’environnement Bash que vous pouvez utiliser dans les commandes cURL :
export FASTLY_SERVICE_ID=<Service-ID>
export FASTLY_API_TOKEN=<API-Token>
Les variables d’environnement exportées ne sont disponibles que dans la session bash en cours et sont perdues lorsque vous fermez le terminal. Vous pouvez redéfinir les variables en exportant une nouvelle valeur. Pour afficher la liste des variables exportées liées à Fastly :
export | grep FASTLY
Ajouter des fragments de code VCL
Ce tutoriel décrit les étapes de base pour ajouter des fragments de code personnalisés à l’aide de l’API Fastly .
Conditions préalables
-
Votre environnement doit être configuré pour utiliser le réseau CDN Fastly. Voir Configuration des services Fastly.
-
Assurez-vous d’exécuter la dernière version du module Fastly CDN pour le Magento 2. Voir Mise à niveau du module Fastly.
-
Vérifiez la configuration de l’environnement pour le service Fastly . Voir Vérification de la mise en cache rapide.
-
Vous devez disposer des informations d’identification d’administrateur pour accéder aux environnements d’évaluation et de production.
Étape 1 : Rechercher la version VCL active
Utilisez l’opération Fastly API get version pour obtenir le numéro de version VCL actif :
curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/active
Dans la réponse JSON, notez le numéro de version VCL actif renvoyé dans la clé number
, par exemple "number": 99
. Vous avez besoin du numéro de version lorsque vous clonez le VCL pour le modifier.
{
"testing": false,
"locked": true,
"number": 99,
"active": true,
"service_id": "872zhjyxhto5SIRb3GAE0",
"staging": false,
"created_at": "2019-01-29T22:38:53Z",
"deleted_at": null,
"comment": "Magento Module uploaded VCL",
"updated_at": "2019-01-29T22:39:06Z",
"deployed": false
}
Enregistrez le numéro de version actif dans une variable d’environnement Bash pour l’utiliser dans les requêtes API suivantes :
export FASTLY_VERSION_ACTIVE=<Version>
Étape 2 : clonez la version VCL active et tous les fragments de code
Avant de pouvoir ajouter ou modifier des fragments de code VCL personnalisés, vous devez créer une copie de la version VCL active pour la modifier. Utilisez l’opération Fastly API clone :
curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_VERSION_ACTIVE/clone -X PUT
Dans la réponse JSON, le numéro de version est incrémenté et la valeur de clé active est false
. Vous pouvez modifier localement la nouvelle version inactive de VCL.
{
"testing": false,
"locked": false,
"number": 100,
"active": false,
"service_id": "vW2bLFWhhto5SIRb3GAE0",
"staging": false,
"created_at": "2019-01-29T22:38:53Z",
"deleted_at": null,
"comment": "Magento Module uploaded VCL",
"updated_at": "2019-01-29T22:39:06Z",
"deployed": false
}
Enregistrez le nouveau numéro de version dans une variable d’environnement Bash à utiliser dans les commandes suivantes :
export FASTLY_EDIT_VERSION=<Version>
Étape 3 : créer un fragment de code VCL personnalisé
Créez et enregistrez votre code VCL personnalisé dans un fichier JSON avec le contenu et le format suivants :
{
"name": "<name>",
"dynamic": "0",
"type": "<type>",
"priority": "100",
"content": "<code all in one line>"
}
Les valeurs sont les suivantes :
-
name
: nom du fragment de code VCL. -
dynamic
: indique s'il s'agit d'un extrait de code normal ou d'un extrait de code dynamique. -
type
: spécifie l'emplacement d'insertion du fragment de code généré, tel queinit
(au-dessus des sous-routines) etrecv
(dans les sous-routines). Voir Valeurs d’objet de fragment de code VCL Fastly pour plus d’informations sur ces valeurs. -
priority
: valeur comprise entre1
et100
qui détermine le moment d'exécution du code de fragment de code VCL personnalisé. Les fragments de code VCL personnalisés avec des valeurs inférieures s’exécutent en premier.Tout le code VCL par défaut du module Fastly VCL a une
priority
de50
. Si vous voulez qu'une action se produise en dernier ou pour remplacer le code VCL par défaut, utilisez un numéro supérieur, tel que100
. Pour exécuter immédiatement le code de fragment de code VCL personnalisé, définissez la priorité sur une valeur inférieure, telle que5
. -
content
: fragment de code VCL à exécuter sur une ligne, sans sauts de ligne. Voir Exemple de fragment de code VCL personnalisé.
Étape 4 : Ajouter le fragment de code VCL à la configuration Fastly
Utilisez l’opération Fastly API create snippet pour ajouter le fragment de code VCL personnalisé à la version VCL.
curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_EDIT_VERSION/snippet -H 'Content-Type: application/json' -X POST --data @<filename.json>
Le <filename.json>
correspond au nom du fichier que vous avez préparé à l’étape précédente. Répétez cette commande pour chaque extrait de code VCL.
Si vous recevez une réponse 500 Internal Server Error
du service Fastly , vérifiez la syntaxe du fichier JSON pour vous assurer que vous téléchargez un fichier valide.
Étape 5 : valider et activer les fragments de code VCL personnalisés
Après avoir ajouté un fragment de code VCL personnalisé, Fastly insère le fragment de code dans la version VCL que vous modifiez. Pour appliquer les modifications, effectuez les étapes suivantes pour valider le code de fragment de code VCL et activer la version VCL.
-
Utilisez l’opération Fastly API validate VCL version pour vérifier le code VCL mis à jour.
curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_EDIT_VERSION/validate
Si l’API Fastly renvoie une erreur, corrigez le problème et validez à nouveau la version VCL mise à jour.
-
Utilisez l’opération Fastly API activate pour activer la nouvelle version de VCL.
curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_EDIT_VERSION/activate -X PUT
Référence rapide d’API pour les fragments de code VCL
Ces exemples de requête API utilisent des variables d’environnement exportées pour fournir les informations d’identification permettant de s’authentifier avec Fastly. Pour plus d’informations sur ces commandes, voir Référence de l’API Fastly.
-
Obtenir le numéro de version VCL actif
curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/active
-
Liste de tous les fragments de code VCL standard associés à un service
curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_VERSION/snippet
-
Vérifier un fragment de code individuel
curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_VERSION/snippet/<snippet_name>
Le
<snippet_name>
est le nom d’un fragment de code, tel quemy_regular_snippet
. -
Mettre à jour un fragment de code
Modifiez le fichier JSON préparé et envoyez la requête suivante :
curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_VERSION/snippet/<snippet_name> -H 'Content-Type: application/json' -X PUT --data @<filename.json>
-
Supprimer un fragment de code VCL individuel
Obtenez une liste de fragments de code et utilisez la commande
curl
suivante avec le nom de fragment de code spécifique à supprimer :curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_VERSION/snippet/<snippet_name> -X DELETE
-
Remplacer les valeurs dans le code VCL Fastly par défaut
Créez un fragment de code avec des valeurs mises à jour et attribuez-lui une priorité de
100
.
Fragments de code ne pouvant pas être affichés/modifiés dans l’administration Commerce
Vous ne pouvez pas afficher ni modifier certains fragments de code directement dans Commerce Admin. Par exemple, extraits dynamiques. Dans la section Fragments de code VCL personnalisés , vous ne verrez pas les fragments de code qui ont été ajoutés directement par l’équipe de support cloud au tableau de bord de gestion Fastly.
Pour observer les fragments de code ajoutés par l’équipe d’assistance cloud, procédez comme suit
-
Accédez à la section Outils.
-
Cliquez sur Répertorier toutes les versions en regard de Historique des versions.
-
Cliquez sur l’icône représentant un œil en regard de la version de VCL applicable pour afficher les fragments de code existants.