Overview API
Cet article de référence couvre les bases de l’API, y compris la terminologie commune et un aperçu des clés de l’API REST, des permissions et de la manière de les sécuriser.
Collection d’API REST de Braze
| Collection | Objectif |
|---|---|
| Catalogues | Créez et gérez des catalogues et des éléments de catalogue à référencer dans vos campagnes Braze. |
| Ingestion de données cloud | Gérez les intégrations et les synchronisations de votre entrepôt de données. |
| Listes et adresses e-mail | Configurez et gérez la synchronisation bidirectionnelle entre Braze et vos paramètres d’e-mail. |
| Exporter | Accédez et exportez divers détails de vos campagnes, Canvas, KPI, et plus encore. |
| Messages | Planifiez, envoyez et gérez vos campagnes et vos canevas. |
| Centre de préférences | Créez votre centre de préférences et actualisez son style. |
| SCIM | Gérer les identités des utilisateurs dans les applications et services basés sur le cloud. |
| SMS | Gérez les numéros de téléphone de vos utilisateurs dans vos groupes d’abonnements. |
| Groupes d’abonnement | Répertoriez et mettez à jour les groupes d’abonnement SMS et e-mail stockés dans le tableau de bord de Braze. |
| Modèles | Créez et mettez à jour des modèles pour les envois de messages par e-mail et les blocs de contenu. |
| Données utilisateur | Identifiez, suivez et gérez vos utilisateurs. |
Définitions relatives aux API
Voici un aperçu des termes que vous pouvez rencontrer dans la documentation de l’API REST de Braze.
Endpoints
Braze gère un certain nombre d’instances différentes pour notre tableau de bord et nos endpoints REST. Lorsque votre compte est approvisionné, vous vous connectez à l’une des URL suivantes. Utilisez le bon Endpoint REST en vous basant sur l’instance qui vous a été provisionnée. En cas de doute, ouvrez un ticket d’assistance ou utilisez le tableau suivant pour faire correspondre l’URL du tableau de bord que vous utilisez au bon endpoint REST.
Lorsque vous utilisez des endpoints pour les appels API, utilisez l’endpoint REST.
Pour l’intégration SDK, utilisez l’endpoint SDK et non pas l’endpoint REST.
| L’instance, l’URL, l’endpoint REST, l’endpoint SDK. | |||
| |— | — | — | |
| US-01 | https://dashboard-01.braze.com |
https://rest.iad-01.braze.com |
sdk.iad-01.braze.com |
| US-02 | https://dashboard-02.braze.com |
https://rest.iad-02.braze.com |
sdk.iad-02.braze.com |
| US-03 | https://dashboard-03.braze.com |
https://rest.iad-03.braze.com |
sdk.iad-03.braze.com |
| US-04 | https://dashboard-04.braze.com |
https://rest.iad-04.braze.com |
sdk.iad-04.braze.com |
| US-05 | https://dashboard-05.braze.com |
https://rest.iad-05.braze.com |
sdk.iad-05.braze.com |
| US-06 | https://dashboard-06.braze.com |
https://rest.iad-06.braze.com |
sdk.iad-06.braze.com |
| US-07 | https://dashboard-07.braze.com |
https://rest.iad-07.braze.com |
sdk.iad-07.braze.com |
| US-08 | https://dashboard-08.braze.com |
https://rest.iad-08.braze.com |
sdk.iad-08.braze.com |
https://dashboard.us-10.braze.com |
https://rest.us-10.braze.com |
sdk.us-10.braze.com |
|
| EU-01 | https://dashboard-01.braze.eu |
https://rest.fra-01.braze.eu |
sdk.fra-01.braze.eu |
| EU-02 | https://dashboard-02.braze.eu |
https://rest.fra-02.braze.eu |
sdk.fra-02.braze.eu |
| AU-01 | https://dashboard.au-01.braze.com |
https://rest.au-01.braze.com |
sdk.au-01.braze.com |
| ID-01 | https://dashboard.id-01.braze.com |
https://rest.id-01.braze.com |
sdk.id-01.braze.com |
Limites de l’API
Pour la plupart des API, la limite de débit par défaut définie par Braze est de 250 000 requêtes par heure. Toutefois, certains types de demandes se voient appliquer leur propre limite de débit afin de mieux gérer les gros volumes de données de la base de clients. Consultez les limites de débit de l’API](/docs/fr/api/api_limits/) pour plus d’informations
ID utilisateur
- ID externe: Le
external_idsert d’identifiant utilisateur unique pour lequel vous soumettez des données. Cet identifiant doit être identique à celui que vous avez défini dans le SDK Braze afin d’éviter de créer plusieurs profils pour le même utilisateur. - Braze user ID:
braze_idsert d’identifiant unique de l’utilisateur défini par Braze. Vous pouvez utiliser cet identifiant pour supprimer des utilisateurs par le biais de l’API REST en plus de external_ids.
Pour plus d’informations, consultez les articles suivants en fonction de votre plateforme : iOS, Android et Web.
À propos des clés API REST
Une clé d’interface de programmation d’applications REST (REST API key) est un code unique que vous transmettez à une API pour authentifier l’appel à l’API et identifier l’application ou l’utilisateur appelant. Vous accédez à l’API à l’aide de requêtes web HTTPS vers l’endpoint de l’API REST de votre entreprise. Les clés API REST fonctionnent en tandem avec les clés App Identifier pour suivre, accéder, envoyer, exporter et analyser les données afin de s’assurer que tout se passe bien.
Chez Braze, les espaces de travail et les clés API vont de pair. Les espaces de travail sont conçus pour héberger des versions de la même application sur plusieurs plateformes. De nombreux clients utilisent également des espaces de travail pour contenir des versions gratuites et premium de leurs applications sur la même plateforme. Comme vous pouvez le constater, ces espaces de travail utilisent également l’API REST et possèdent leurs propres clés API REST. Ces clés peuvent être personnalisées individuellement pour inclure l’accès à des endpoints spécifiques sur l’API. Chaque appel à l’API doit inclure une clé ayant accès à l’endpoint.
Nous faisons référence à la clé API REST et à la clé API de l’espace de travail en tant que api_key. Le api_key est inclus dans chaque requête en tant qu’en-tête de requête et agit comme une clé d’authentification qui vous permet d’utiliser nos API REST. Ces API REST sont utilisées pour suivre les utilisateurs, envoyer des messages, exporter des données utilisateur, etc. Lorsque vous créez une nouvelle clé API REST, vous devez lui donner accès à des endpoints spécifiques. En affectant des autorisations spécifiques à une clé API, vous pouvez limiter de façon précise les appels qu’une clé API peut authentifier.
En plus des clés API REST, il existe un troisième type appelé Clés d’identification qui permet de référencer des objets spécifiques tels que des applications, des modèles, des Canvas, des campagnes, des cartes de contenu et des segments de l’API. Pour plus d’informations, reportez-vous aux types d’identifiants API.
Créer des clés API REST
Pour créer une nouvelle clé d’API REST :
- Allez dans Paramètres > API et identifiants.
- Sélectionnez Créer une clé API.
- Donnez un nom à votre nouvelle clé pour l’identifier d’un coup d’œil.
- Spécifier les sous-réseaux et adresses IP autorisés pour cette nouvelle clé.
- Sélectionnez les autorisations que vous souhaitez associer à votre nouvelle clé.
N’oubliez pas qu’après avoir créé une nouvelle clé API, vous ne pouvez pas modifier l’étendue des autorisations ou les adresses IP autorisées. Cette restriction est en place pour des raisons de sécurité. Si vous devez modifier le périmètre d’une clé, créez une nouvelle clé avec les autorisations mises à jour et implémentez cette clé à la place de l’ancienne. Une fois la mise en œuvre terminée, vous pouvez supprimer l’ancienne clé.
Autorisations de clé API REST
Les autorisations de clés API sont des autorisations que vous pouvez affecter à un utilisateur ou un groupe pour limiter leur accès à certains appels API. Pour afficher la liste des autorisations de votre clé API, allez dans Paramètres > API et identifiants, et sélectionnez votre clé API.
| Autorisation | Endpoint | Description |
|---|---|---|
users.track |
/users/track |
Enregistrer les attributs utilisateur, les événements personnalisés et les achats. |
users.delete |
/users/delete |
Supprimer un utilisateur. |
users.alias.new |
/users/alias/new |
Créer un nouvel alias pour un utilisateur existant. |
users.identify |
/users/identify |
Identifier un utilisateur alias d’un ID externe. |
users.export.ids |
/users/export/ids |
Extraire les données de profil utilisateur par ID d’utilisateur. |
users.export.segment |
/users/export/segment |
Demande d’informations sur le profil utilisateur par segmentation. |
users.merge |
/users/merge |
Fusionne deux utilisateurs existants. |
users.external_ids.rename |
/users/external_ids/rename |
Changer l’ID externe d’un utilisateur existant. |
users.external_ids.remove |
/users/external_ids/remove |
Supprimer l’ID externe d’un utilisateur existant. |
users.alias.update |
/users/alias/update |
Mettre à jour un alias pour un utilisateur existant. |
users.export.global_control_group |
/users/export/global_control_group |
Extraire les données des profils d’utilisateur dans le groupe de contrôle global. |
| Autorisation | Endpoint | Description |
|---|---|---|
email.unsubscribe |
/email/unsubscribes |
Extraire les adresses e-mail désinscrites. |
email.status |
/email/status |
Modifier l’état de l’adresse e-mail. |
email.hard_bounces |
/email/hard_bounces |
Extraire les adresses e-mail ayant reçu un échec d’envoi définitif. |
email.bounce.remove |
/email/bounce/remove |
Supprimer des adresses e-mail de votre liste d’e-mails ayant reçu un échec d’envoi définitif. |
email.spam.remove |
/email/spam/remove |
Supprimer les adresses e-mail de votre liste de spam. |
email.blacklist |
/email/blacklist |
Liste de blocage des adresses e-mail. |
| Autorisation | Endpoint | Description |
|---|---|---|
campaigns.trigger.send |
/campaigns/trigger/send |
Déclencher l’envoi d’une campagne existante. |
campaigns.trigger.schedule.create |
/campaigns/trigger/schedule/create |
Planifiez l’envoi d’une campagne avec réception/distribution déclenchée par l’API. |
campaigns.trigger.schedule.update |
/campaigns/trigger/schedule/update |
Mettre à jour une campagne planifiée avec une livraison déclenchée par API. |
campaigns.trigger.schedule.delete |
/campaigns/trigger/schedule/delete |
Supprimez une campagne planifiée avec une réception/distribution déclenchée par l’API. |
campaigns.list |
/campaigns/list |
Extraire la liste des campagnes. |
campaigns.data_series |
/campaigns/data_series |
Extraire les données d’analyse d’une campagne sur une période donnée. |
campaigns.details |
/campaigns/details |
Extraire les données d’une campagne spécifique. |
sends.data_series |
/sends/data_series |
Extraire l’analyse des messages envoyés sur une période donnée. |
sends.id.create |
/sends/id/create |
Créez un ID d’envoi pour le suivi de l’envoi des messages. |
campaigns.url_info.details |
/campaigns/url_info/details |
Extraire les données des URL d’une variation de message donnée dans une campagne. |
transactional.send |
/transactional/v1/campaigns/{campaign_id}/send |
Permet d’envoyer des messages transactionnels à l’aide de l’endpoint de messagerie transactionnelle. |
| Autorisation | Endpoint | Description |
|---|---|---|
canvas.trigger.send |
/canvas/trigger/send |
Déclencher l’envoi d’un canvas existant. |
canvas.trigger.schedule.create |
/canvas/trigger/schedule/create |
Planifiez l’envoi d’un canvas avec réception/distribution déclenchée par l’API. |
canvas.trigger.schedule.update |
/canvas/trigger/schedule/update |
Mettre à jour un canvas planifié avec un envoi déclenché par API. |
canvas.trigger.schedule.delete |
/canvas/trigger/schedule/delete |
Supprimer un canvas programmé avec un envoi déclenché par API. |
canvas.list |
/canvas/list |
Extraire la liste des Canvas. |
canvas.data_series |
/canvas/data_series |
Extraire l’analyse de Canvas sur une période donnée. |
canvas.details |
/canvas/details |
Extraire les données d’un Canvas spécifique. |
canvas.data_summary |
/canvas/data_summary |
Extraire les cumuls des analyses de Canvas sur une période donnée. |
canvas.url_info.details |
/canvas/url_info/details |
Demande d’informations sur l’URL d’une variation de message spécifique au sein d’une étape du canvas. |
| Autorisation | Endpoint | Description |
|---|---|---|
segments.list |
/segments/list |
Demande d’une liste de segments. |
segments.data_series |
/segments/data_series |
Demande d’analyses/analytiques de segments sur une période donnée. |
segments.details |
/segments/details |
Demande de détails sur un segment spécifique. |
| Autorisation | Endpoint | Description |
|---|---|---|
purchases.product_list |
/purchases/product_list |
Extraire la liste des produits achetés dans votre application. |
purchases.revenue_series |
/purchases/revenue_series |
Extraire le montant total dépensé par jour dans votre application sur une période donnée. |
purchases.quantity_series |
/purchases/quantity_series |
Extraire le nombre total d’achats effectués par jour dans votre application sur une période donnée. |
| Autorisation | Endpoint | Description |
|---|---|---|
events.list |
/events/list |
Extraire la liste des événements personnalisés. |
events.data_series |
/events/data_series |
Extraire les occurrences d’un événement personnalisé sur une période donnée. |
| Autorisation | Endpoint | Description |
|---|---|---|
sessions.data_series |
/sessions/data_series |
Extraire les sessions par jour sur une période donnée. |
| Autorisation | Endpoint | Description |
|---|---|---|
kpi.dau.data_series |
/kpi/dau/data_series |
Extraire les utilisateurs actifs uniques par jour sur une période donnée. |
kpi.mau.data_series |
/kpi/mau/data_series |
Extraire les utilisateurs actifs uniques sur une fenêtre de 30 jours glissants sur une période donnée. |
kpi.new_users.data_series |
/kpi/new_users/data_series |
Extraire les nouveaux utilisateurs par jour sur une période donnée. |
kpi.uninstalls.data_series |
/kpi/uninstalls/data_series |
Extraire les désinstallations d’applications par jour sur une période donnée. |
| Autorisation | Endpoint | Description |
|---|---|---|
templates.email.create |
/templates/email/create |
Créer un nouveau modèle d’e-mail sur le tableau de bord. |
templates.email.info |
/templates/email/info |
Extraire les données d’un modèle spécifique. |
templates.email.list |
/templates/email/list |
Extraire la liste des modèles d’e-mail. |
templates.email.update |
/templates/email/update |
Mettre à jour un modèle d’e-mail stocké sur le tableau de bord. |
| Autorisation | Description |
|---|---|
sso.saml.login |
Configurer l’identifiant initié par le fournisseur d’identité. Pour plus d’informations, reportez-vous à l’identification initiée par le fournisseur de services (PS). |
| Autorisation | Endpoint | Description |
|---|---|---|
content_blocks.info |
/content_blocks/info |
Extraire les données d’un modèle spécifique. |
content_blocks.list |
/content_blocks/list |
Extraire la liste des blocs de contenu. |
content_blocks.create |
/content_blocks/create |
Créer un nouveau bloc de contenu sur le tableau de bord. |
content_blocks.update |
/content_blocks_update |
Mettre à jour un bloc de contenu existant dans le tableau de bord. |
| Autorisation | Endpoint | Description |
|---|---|---|
preference_center.get |
/preference_center/v1/{preferenceCenterExternalId} |
Obtenir un centre de préférences. |
preference_center.list |
/preference_center/v1/list |
Répertorier les centres de préférences. |
preference_center.update |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalID} |
Créez ou mettez à jour un centre de préférences. |
preference_center.user.get |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId} |
Obtenir le lien d’un centre de préférence pour un utilisateur. |
| Autorisation | Endpoint | Description |
|---|---|---|
subscription.status.set |
/subscription/status/set |
Définir le statut du groupe d’abonnement. |
subscription.status.get |
/subscription/status/get |
Obtenir le statut du groupe d’abonnement. |
subscription.groups.get |
/subscription/user/status |
Obtenir le statut des groupes d’abonnement auxquels des utilisateurs spécifiques sont explicitement abonnés et désabonnés. |
| Autorisation | Endpoint | Description |
|---|---|---|
sms.invalid_phone_numbers |
/sms/invalid_phone_numbers |
Extraire les numéros de téléphone non valides. |
sms.invalid_phone_numbers.remove |
/sms/invalid_phone_numbers/remove |
Supprimer le drapeau de numéro de téléphone non valide d’utilisateurs. |
| Autorisation | Endpoint | Description |
|---|---|---|
catalogs.add_items |
/catalogs/{catalog_name}/items |
Ajouter plusieurs produits à un catalogue existant. |
catalogs.update_items |
/catalogs/{catalog_name}/items |
Mettre à jour plusieurs produits dans un catalogue existant. |
catalogs.delete_items |
/catalogs/{catalog_name}/items |
Supprimer plusieurs produits d’un catalogue existant. |
catalogs.get_item |
/catalogs/{catalog_name}/items/{item_id} |
Obtenir un produit unique d’un catalogue existant. |
catalogs.update_item |
/catalogs/{catalog_name}/items/{item_id} |
Mettre à jour un produit unique dans un catalogue existant. |
catalogs.create_item |
/catalogs/{catalog_name}/items/{item_id} |
Créer un produit unique dans un catalogue existant. |
catalogs.delete_item |
/catalogs/{catalog_name}/items/{item_id} |
Supprimer un produit unique d’un catalogue existant. |
catalogs.replace_item |
/catalogs/{catalog_name}/items/{item_id} |
Remplacer un produit unique d’un catalogue existant. |
catalogs.create |
/catalogs |
Créer un catalogue. |
catalogs.get |
/catalogs |
Obtenir une liste de catalogues |
catalogs.delete |
/catalogs/{catalog_name} |
Supprimer un catalogue. |
catalogs.get_items |
/catalogs/{catalog_name}/items |
Obtenir l’aperçu des produits d’un catalogue existant. |
catalogs.replace_items |
/catalogs/{catalog_name}/items |
Remplacer des articles dans un catalogue existant. |
| Autorisation | Endpoint | Description |
|---|---|---|
sdk_authentication.create |
/app_group/sdk_authentication/create |
Créez une nouvelle clé d’authentification SDK pour votre application. |
sdk_authentication.primary |
/app_group/sdk_authentication/primary |
Marquez une clé d’authentification SDK comme clé principale pour votre application. |
sdk_authentication.delete |
/app_group/sdk_authentication/delete |
Supprimez une clé d’authentification SDK pour votre application. |
sdk_authentication.keys |
/app_group/sdk_authentication/keys |
Obtenez toutes les clés d’authentification du SDK pour votre application. |
Gestion des clés API REST
Vous pouvez afficher les détails des clés API REST existantes ou les supprimer à partir de Paramètres > API et identifiants > onglet Clés API. Notez que vous ne pouvez pas modifier les clés API REST après les avoir créées.
L’onglet Clés API contient les informations suivantes pour chaque clé :
| Champ | Description |
|---|---|
| Nom de clé API | Nom donné à la clé lors de sa création. |
| Identifiant | La clé API. |
| Créé par | L’adresse e-mail de l’utilisateur qui a créé la clé. Ce champ indique “N/A” pour les clés créées avant juin 2023. |
| Date de création | Date de création de cette clé. |
| Vu pour la dernière fois | Date de la dernière utilisation de cette clé. Ce champ affiche “N/A” pour les clés qui n’ont jamais été utilisées. |
Pour afficher les détails d’une clé API, passez la souris sur la clé et sélectionnez View. Cela comprend toutes les autorisations dont dispose cette clé, les adresses IP inscrites sur la liste blanche (le cas échéant) et si cette clé est inscrite sur la liste blanche des adresses IP de Braze.
Notez que lors de la suppression d’un utilisateur, Braze ne supprime pas les clés API associées que l’utilisateur a créées. Pour supprimer une clé, survolez-la et sélectionnez Supprimer.
Sécurité clé API REST
Les clés API servent à authentifier les appels de l’API. Quand vous créez une nouvelle clé API REST, vous devez lui accorder l’accès à des endpoints spécifiques. En affectant des autorisations spécifiques à une clé API, vous pouvez limiter de façon précise les appels qu’une clé API peut authentifier.
Étant donné que les clés API REST permettent d’accéder à des endpoints API REST potentiellement sensibles, sécurisez ces clés et partagez-les uniquement avec des partenaires de confiance. Elles ne doivent jamais être exposées publiquement. Par exemple, n’utilisez pas cette clé pour faire des appels AJAX depuis votre site Web ou pour l’exposer autrement de façon publique.
Une bonne pratique de sécurité est d’accorder à un utilisateur uniquement les accès nécessaires pour qu’il puisse accomplir son travail ; ce principe peut également être appliqué aux Clés API en affectant des autorisations pour chaque clé. Ces autorisations vous offrent une meilleure sécurité et un meilleur contrôle sur les différentes parties de votre compte.
Étant donné que les clés d’API REST permettent d’accéder à des endpoints d’API REST potentiellement sensibles, assurez-vous qu’elles sont stockées et utilisées en toute sécurité. Par exemple, n’utilisez pas cette clé pour faire des appels AJAX depuis votre site Web ou pour l’exposer autrement de façon publique.
Si vous exposez accidentellement une clé, vous pouvez la supprimer à partir de la console de développement. Pour obtenir de l’aide sur ce processus, ouvrez un ticket d’assistance.
Liste d’adresses IP autorisées
Pour renforcer la sécurité, vous pouvez établir une liste des adresses IP et sous-réseaux qui sont exclusivement autorisés à envoyer des requêtes à l’API REST pour une clé API REST donnée. Vous définissez pour cela une liste d’autorisations, également appelée « Liste blanche ». Pour autoriser des adresses IP ou des sous-réseaux spécifiques, indiquez-les dans la section **Liste blanche d’adresses IP (Whitelist IPs) **lors de la création d’une nouvelle clé API REST :
Si vous n’en spécifiez aucune, les requêtes pourront être envoyées depuis n’importe quelle adresse IP.
Si vous créez un webhook Braze à Braze et que vous utilisez le allowlisting, consultez la liste des IP à mettre sur liste blanche.
Ressources complémentaires
Bibliothèque client Ruby
Si vous implémentez Braze à l’aide de Ruby, vous pouvez utiliser la bibliothèque client Ruby pour réduire le temps d’importation des données. Une bibliothèque cliente est une collection de code spécifique à un langage de programmation (dans ce cas, Ruby) qui facilite l’utilisation d’une API.
La bibliothèque client Ruby prend en charge les endpoints utilisateur.
Cette bibliothèque client est en version bêta. Pour contribuer à l’amélioration de cette bibliothèque, envoyez vos commentaires à [email protected].
Modifier cette page sur GitHub