Gestion des versions

La version actuelle de l'API Marketing est v21.0.

La plateforme de Facebook dispose d’un noyau et d’un modèle de gestion des versions étendu. Grâce à la gestion des versions de l’API Marketing, toutes les modifications importantes figurent dans une nouvelle version. Plusieurs versions des API Marketing ou des SDK peuvent exister simultanément, avec une fonctionnalité différente dans chaque version.

Les équipes de développement doivent savoir à l’avance à quel moment une API Marketing ou un SDK connaîtra des modifications. Même si vous disposez toujours d’une fenêtre de 90 jours pour adopter les modifications, il vous revient de choisir comment et quand passer à la nouvelle version.

Calendriers des versions

Lorsqu’une nouvelle version de l’API Marketing est lancée, nous continuons de prendre en charge la version précédente pendant au moins 90 jours. Vous disposez donc de ce délai pour passer à la nouvelle version. Pendant cette période de grâce, vous pouvez appeler à la fois la version actuelle et la version obsolète, et disposez de 90 jours pour passer à la nouvelle version. À la fin de cette période de 90 jours, la version obsolète cesse de fonctionner. Lorsqu’une version n’est plus disponible, tous les appels passés à ce numéro de version échouent ou sont transférés vers la version disponible suivante.

Par exemple, la version 17.0 de l'API Marketing a été publiée le 23 mai 2023, et la version 16.0 a expiré le 6 février 2024, ce qui a laissé plus de 90 jours aux utilisateur·ices pour changer de version.

Voici un exemple de calendrier. Notez qu’il est possible que nous ne sortions pas de nouvelle version au bout des 90 jours suivant la fin de prise en charge de la version précédente. Dans cet exemple, la prise en charge de la version 16.0 s’est arrêtée quelque temps avant la mise en ligne de la version 18.0 :

Pour les SDK, une version reste toujours disponible, puisqu’il s’agit d’un package à télécharger. Toutefois, au-delà de sa date d’expiration, il est possible qu’elle dépende d’API Marketing ou de méthodes qui ne fonctionnent plus. Vous devez donc en déduire que le SDK expiré n’est plus fonctionnel.

Envoi de requêtes avec version

Tous les points de terminaison de l’API Marketing sont disponibles par le biais d’un processus avec version. Ajoutez préalablement la version au début du chemin de requête. Par exemple :

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0/me/adaccounts"

Cela fonctionne pour toutes les versions, sous la forme générale suivante :

https://graph.facebook.com/v{n}/{request-path}

où n correspond à la version nécessaire. Vous trouverez une liste complète des versions disponibles dans notre changelog. Tous nos documents de référence sur l’API Marketing fournissent des informations sur chaque version.

Migrations

Les migrations sont réservées uniquement aux scénarios particuliers dans lesquels des modifications doivent être apportées et ne peuvent pas passer par la gestion des versions. Généralement, c’est le cas si le modèle de données sous-jacent a changé. Les migrations s’appliquent à l’ensemble des versions.

Les migrations qui sont toujours en cours sont répertoriées sur notre page des migrations. Les migrations font l’objet d’une fenêtre d’au moins 90 jours pendant laquelle vous devez migrer votre application. Lorsqu’une fenêtre débute, le comportement post-migration devient le comportement par défaut pour les nouvelles applications. Ensuite, lorsque la fenêtre de migration se referme, le comportement préalable à la migration n’est plus du tout disponible.

Gérer les migrations par l’intermédiaire de l’API Graph

Les migrations peuvent être gérées par le biais du champ réservé aux migrations dans le nœud /app :

Vous pouvez effectuer un appel de mise à jour sur l’arête pour activer et désactiver les migrations.

Gérer les migrations par l’intermédiaire de l’Espace App

Vous pouvez activer et désactiver les migrations disponibles dans l’Espace App sous Paramètres > Migrations. Veuillez noter que la liste des migrations peut être différente de celle représentée sur l’image ci-dessous, car les migrations disponibles sont différentes selon les applications et la période. Si vous remarquez une migration Use Graph API v2.0 by default, elle est destinée uniquement à l’API Graph, et non à l’API Marketing.

Activation temporaire des migrations côté client

Au lieu d’activer la migration dans votre Espace App ou par le biais de l’API Marketing, il est possible d’ajouter à vos appels d’API Marketing un indicateur spécial qui configure la migration. Cet indicateur, intitulé migrations_override, nécessite que vous indiquiez un grand objet binaire JSON qui décrive les migrations à activer ou désactiver. Par exemple, si vous effectuez un appel brut, vous pouvez transmettre :

http://graph.facebook.com/path?
  migrations_override={"migration1":true, "migration2":false}

Vous pouvez ainsi appeler la nouvelle API Marketing par le biais de mises à jour de client plutôt que de mettre à jour tous les appelants pour qu’ils appellent la nouvelle API Marketing simultanément. C’est également très utile pour le débogage.

Le nom de ces migrations est disponible dans le nœud /app mentionné ci-dessus.

Mise à niveau automatique de la version

Compte tenu de la rotation rapide des versions de l'API Marketing, environ tous les quatre mois, nous simplifions le processus de mise à niveau. À compter de mai 2024, nous activerons la fonctionnalité de mise à niveau automatique de la version pour les points de terminaison de l’API Marketing qui ne sont pas affectés d’une version à l’autre. Cela signifie qu'entre une version prochainement obsolète et la version disponible suivante, si un point de terminaison n'est pas affecté, la plateforme mettra à jour l'appel vers la version disponible suivante, plutôt que de faire échouer directement la requête. Ce changement vise à assurer une expérience plus fluide et plus efficace avec l'API.

Par exemple, le 14 mai 2024, la version 17.0 ne sera plus prise en charge. Selon le changelog de la version 18.0, les points de terminaison suivants seront affectés :

• POST /act_{ad-account-id}/reachfrequencypredictions
• GET /act_{ad-account-id}/reachestimate
• GET /act_{ad-account-id}/delivery_estimate
• POST /act_{ad-account-id}/adsets
• POST /{adset-id}
• POST /act_{ad-account-id}/saved_audiences
• POST /{saved-audience-id}
• POST /act_{ad-account-id}/credit_cards

Si votre application appelle POST /{adset-id} avec la version 17.0 après la fin de sa prise en charge en date du 14 mai 2024, cette demande d'API échouera, car la mise à niveau automatique n'est pas appliquée aux points de terminaison affectés par la version disponible suivante (version 18.0).

Si votre application appelle GET /{ad-account-id}/insights avec la version 17.0 après la fin de sa prise en charge, la plateforme mettra votre appel à niveau vers la version disponible suivante (version 18.0).

Remarque : si votre application passe déjà des appels avec des versions supérieures à la version 17.0, il ne devrait y avoir aucun changement à la date de fin de prise en charge de cette version.

Pour vérifier les points de terminaison affectés à chaque version, veuillez consulter le changelog de l’API Marketing.

Questions/réponses

Calendriers des versions

Envoi de requêtes avec version

https://graph.facebook.com/v{n}/{request-path}

Mise à niveau automatique de la version

X-Ad-Api-Version-Warning: 'X-Ad-Api-Version-Warning: 'The call has been auto-upgraded to vXXX as vXXX has been deprecated''