API REST d'Unica Campaign
Utilisez l'API REST d'Unica Campaign pour manipuler les campagnes, les offres, les listes d'offres, les attributs et les objets de population ciblée.
Présentation
L'API se base sur les principes REST (Representational State Transfer). Il vous est ainsi plus facile d'écrire et de tester des applications. Vous pouvez utiliser votre navigateur pour accéder aux URL, et vous pouvez utiliser n'importe quel client HTTP standard dans n'importe quel langage de programmation pour interagir avec l'API. Tous les appels d'API doivent être intégralement en minuscules.
Adresse URL de base
L'adresse URL de base est : http://<host>:<port>/Campaign/api/campaign/rest
Ajoutez l'adresse URL de base en préfixe à chaque API répertoriée. Par exemple : http://host:port/Campaign/api/campaign/rest/v1/offers
Liste des API
| Attributs | |
| get: /v1/attributes | Renvoie les métadonnées de tous les attributs définis ou de l'attribut spécifié. |
| post: /v1/attributes/create/{type} | Crée les métadonnées d'attribut pour le type d'objet spécifié. |
| delete: /v1/attributes/delete | Supprime les métadonnées de l'attribut spécifié. |
| get: /v1/attributes/metadata/{type} | Renvoie les métadonnées pour tous les attributs du type spécifié ou de l'attribut spécifié. |
| put: /v1/attributes/update/metadata | Met à jour les valeurs d'attribut pour un objet spécifié. |
| put: /v1/attributes/update/{type}/{id} | Met à jour les valeurs d'attribut pour un objet spécifié ; renvoie les métadonnées pour les attributs spécifiés. |
| get: /v1/attributes/{type}/{id} | Renvoie les métadonnées pour les attributs spécifiés. |
| Campagnes | |
| get: /v1/campaigns | Renvoie la liste des objets d'Unica Campaign sous forme de données JSON. |
| post: /v1/campaigns | Crée une campagne avec les données JSON fournies. |
| get: /v1/campaigns/code | Génère un code de campagne. |
| post: /v1/campaigns/delete | Supprime les campagnes spécifiées. |
| get: /v1/campaigns/metrics | Renvoie les indicateurs pour la campagne spécifiée. |
| post: /v1/campaigns/search | Recherche les campagnes en fonction des informations fournies. |
| get: /v1/campaigns/{campaignid} | Renvoie l'objet de campagne spécifié. |
| put: /v1/campaigns/{campaignid} | Met à jour l'objet de campagne spécifié. |
| delete: /v1/campaigns/{campaignid} | Supprime l'objet de campagne spécifié. |
| Offres | |
| post: /v1/offers | Crée une ou plusieurs offres. |
| post: /v1/offers/delete | Supprime une ou plusieurs offres. |
| get: /v1/offers/gencode | Génère un ou plusieurs codes d'offre uniques. |
| post: /v1/offers/getoffers | Répertorie tous les objets d'offre. |
| post: /v1/offers/retire | Retire une ou plusieurs offres. |
| post: /v1/offers/templates | Renvoie une liste comportant les détails de modèle d'offre. |
| post: /v1/offers/validate | Vérifie s'il existe une seule offre correspondante. |
| Offres v2 | |
| post: /v2/offers | Crée une ou plusieurs offres. |
| post: /v2/offers/delete | Supprime une ou plusieurs offres. |
| get: /v2/offers/gencode | Génère un ou plusieurs codes d'offre uniques. |
| post: /v2/offers/getoffers | Répertorie tous les objets d'offre. |
| post: /v2/offers/retire | Retire une ou plusieurs offres. |
| post: /v2/offers/templates | Renvoie une liste comportant les détails de modèle d'offre. |
| post: /v2/offers/validate | Vérifie s'il existe une seule offre correspondante. |
| get: /v2/offers/search | Retourne une liste des détails des offres. |
| get: /v2/offers | |
| Listes d'offres | |
| get: /v1/offerlist | Renvoie la liste des listes d'offres. |
| put: /v1/offerlist | Met à jour la liste d'offres. |
| post: /v1/offerlist | Crée une liste d'offres. |
| post: /v1/offerlist/createSmartOffer | Crée une liste d'offres dynamique. |
| post: /v1/offerlist/delete | Supprime les listes d'offres. |
| post: /v1/offerlist/retire | Retire les listes d'offres. |
| Objets de population ciblée | |
| get: /v1/targetcells | Renvoie la liste de populations ciblées pour l'ID de campagne spécifié. |
| post: /v1/targetcells | Crée une population ciblée avec les informations fournies. |
| post: /v1/targetcells/delete | Supprime en masse les populations ciblées spécifiées. |
| get: /v1/targetcells/runresults | Renvoie les résultats d'exécution pour les populations ciblées spécifiées. |
| put: /v1/targetcells/update | Met à jour une population ciblée existante avec les informations fournies. |
| delete: /v1/targetcells/{cellid} | Supprime la population ciblée spécifiée. |
Codes d'état HTTP
L'API REST d'Unica Campaign tente de renvoyer les codes de statut HTTP appropriés pour chaque demande. Par exemple :
200 - OK 400 - Demande incorrecte (corrigez l'erreur avant de soumettre à nouveau.) 500 - Erreur de serveur interne (vérifiez <Campaign_home>/logs/campaignweb.log sur le serveur d'applications Web Campaign pour plus de détails.) 404 - Introuvable
Plusieurs ressources en ligne fournissent des informations relatives aux codes HTTP.Infrastructure de sécurité des API Unica
Unica Platform fournit l'infrastructure de sécurité des API implémentées par les produits Unica.
Un ensemble de propriété de configuration sur la page permet aux développeurs de définir la sécurité suivante pour les API fournies par les produits Unica.
- Pour une API de produit spécifique, vous pouvez bloquer l'accès au produit.
- Pour une API de produit spécifique, vous pouvez exiger HTTPS pour la communication entre l'API spécifiée et le produit.
- Pour une API de produit spécifique, vous pouvez exiger l'authentification pour la communication entre l'API spécifiée et le produit.
Les propriétés de configuration qui contrôlent la sécurité de l'API se trouvent sous la catégorie Unica Platform | Sécurité | Gestion de l'API. Chaque produit dispose d'un modèle de propriété de configuration que vous pouvez utiliser pour créer de nouveaux paramètres de sécurité pour les API fournies par ce produit.
Vous pouvez définir et modifier les paramètres de sécurité d'une API de manière appropriée pour les tests d'unités ou le déploiement ou au cours du cycle de vie des API.
L'infrastructure de sécurité prend actuellement uniquement en charge les API de Unica Campaign.
L'infrastructure de sécurité Unica Platform prend en charge les deux options d'authentification suivantes pour l'accès aux API protégées. Vous pouvez utiliser l'une ou l'autre, en fonction de votre environnement.
- Les utilisateurs internes qui sont enregistrés sur Unica Platform peuvent être authentifiés à l'aide de leurs données d'identification de connexion Unica Platform pour obtenir un jeton sécurisé.
- Les utilisateurs externes qui font partie d'une fédération Unica Platform qui est configuré pour utilisation, peuvent être authentifiés via le serveur du fournisseur d'identité.
Authentification d'utilisateurs internes avec l'API de connexion Unica Platform
Pour authentifier des utilisateurs internes dans des applications client, utilisez l'API Unica Platform login afin de générer des jetons sécurisés. Vous pouvez ensuite appeler n'importe quelle API protégée en transmettant les paramètres requis dans l'en-tête de requête, en plus des paramètres attendus par l'API.
Le filtre de sécurité intercepte ces demandes protégées, les valide et les transmet pour traitement.
Une fois l'utilisateur Unica Platform authentifié, le filtre de sécurité Unica Platform ajoute le nom de connexion de l'utilisateur à la demande en tant qu'attribut de la clé USER_NAME_STRING avant de le transmettre au produit pour traitement.
Les jetons sécurisés ont un cycle de vie par défaut de 15 secondes. Une fois ce délai expiré, le jeton ne peut plus être utilisé pour appeler une API protégée. Chaque fois que l'API Unica Platform login est appelée pour un utilisateur, l'intégralité des jetons de sécurité précédents pour cet utilisateur est invalidée.
Vous pouvez changer le cycle de vie des jetons sécurisés en définissant la valeur de la propriété Token lifetime située sur la page sous la catégorie Général | Divers.
Exemple d'URL
http[s]://host:port/unica/api/manager/authentication/login/
Paramètres d'en-tête
| Paramètre | Description |
|---|---|
| m_user_name | Nom de connexion Unica Platform de l'utilisateur interne. |
| m_user_password | Mot de passe Unica Platform en texte en clair de l'utilisateur interne. |
Réponse
Lorsque la connexion aboutit, la réponse est HTTP 200 avec les données JSON suivantes.
m_tokenId- jeton généré de manière aléatoirem_user_name- nom de l'utilisateur connectécreateDate- horodatage au format affiché dans l'exemple suivant, où le fuseau horaire est IST (heure normale de l'Inde) :Mon Jul 06 18:23:35 IST 2015
Lorsque la connexion échoue avec des données d'identification incorrectes, la réponse est HTTP 401 (non autorisé). Lorsque l'API de login est configurée pour être bloquée, la réponse est 403 (interdit). Lorsque l'API de login est configurée pour utiliser HTTPS, et si elle est appelée sur HTTP, la réponse est 403 (interdit).
Pour déconnecter des utilisateurs internes, utilisez l'API de Unica Platform logout.
Déconnexion d'utilisateurs internes avec l'API de déconnexion Unica Platform
Utilisez l'API de Unica Platform logout pour déconnecter des utilisateurs internes et supprimer le jeton sécurisé.
L'API de logout est protégée par défaut. Les paramètres d'authentification sont prévus dans l'en-tête de requête en regard des clés prédéfinies.
Exemple d'URL
http[s]://host:port/unica/api/manager/authentication/logout/
Paramètres d'en-tête
| Paramètre | Description |
|---|---|
| m_user_name | Nom de connexion Unica Platform de l'utilisateur interne. |
| m_tokenId | Jeton sécurisé obtenu via l'authentification. |
| api_auth_mode | Utilisez la valeur manager pour les utilisateurs internes. |
Réponse
Lorsque l'authentification aboutit, la réponse est HTTP 200 et le jeton sécurisé est supprimé. Si la réponse est HTTP 200, l'application client doit confirmer la déconnexion.
Lorsque l'authentification échoue, la réponse est HTTP 401.
Authentification des utilisateurs externes et déconnexion via une fédération
Lorsque Unica Platform est intégré avec une fédération prise en charge, les utilisateurs peuvent se connecter à leur propre système et l'application client obtient un jeton via le serveur IdP (Identity Provider) fourni par Unica Platform.
Une fois qu'un utilisateur fédéré est authentifié, son nom de connexion Unica Platform correspondant est ajouté à la requête comme attribut de la clé USER_NAME_STRING.
La déconnexion doit être effectuée sur le serveur IdP.
Paramètres d'en-tête
Le tableau suivant décrit les paramètres d'en-tête à utiliser lors de l'authentification via le serveur IdP fourni par Unica Platform.
| Paramètre | Description |
|---|---|
| f_userId | ID utilisateur dans la fédération. |
| f_clientId | ID client dans la fédération. |
| f_spId | ID de fournisseur de services dans la fédération. |
| f_tokenId | Jeton de connexion unique du serveur IdP. |
| api_auth_mode | Utilisez la valeur fsso pour l'authentification fédérée. |
Réponse
La réponse est HTTP 200, avec des éléments supplémentaires en fonction de l'API.