Learning Objectives /Objectifs de formation
After completing this unit, you’ll be able to: / Une fois cette unité terminée, vous pourrez :
- Integrate with a Marketing Cloud API securely. / Intégrer en toute sécurité avec une API Marketing Cloud.
- Use access tokens for both REST and SOAP APIs. /Utiliser des jetons d’accès pour les API REST et SOAP.
- Know when to refresh your tokens. /Savoir quand actualiser vos jetons.
Get Your Token / Avoir votre jeton
At Salesforce, we take security seriously. /Chez Salesforce, nous prenons la sécurité au sérieux.
And the Marketing Cloud REST and SOAP APIs are no exception. /Et les API Marketing Cloud REST et SOAP ne font pas exception.
Marketing Cloud provides tenant-specific endpoints to help secure your API requests (more on this in a minute). /Marketing cloud fournit des points de terminaison spécifiques au locataire pour vous d’aider à sécuriser vos demandes d’API (plus d’informations à ce sujet dans une minute).
Plus, you’re required to use OAuth tokens to access these endpoints. /De plus, vous devez utiliser les jetons OAuth pour accéder à ces points de terminaison.
To get those endpoints and tokens, you need to do a few things. /Pour obtenir ces points de terminaison et ces jetons, vous devez faire un peu de configuration.
Both the REST and SOAP APIs require an API integration with Marketing Cloud using an installed package. /Les API REST et SOAP nécessitent une intégration d’API avec Marketing Cloud à l’aide d’un package installé.
After you create the installed package in your Marketing Cloud account, you can request an access token using your client ID and secret. / Après avoir créé le package installé dans votre compte Marketing Cloud, vous pouvez demander un jeton d’accès à l’aide de votre ID client et secret.
Any application that you create extracts that token and uses it to gain access to Marketing Cloud resources. /Toute application que vous créez extrait ce jeton et l’utilise pour accéder aux ressources Marketing Cloud.
Let’s walk through creating an installed package and finding your endpoints. /Voyons comment créer un package installé et trouver vos points de terminaison.
Note / Remarque
The examples in this unit use the REST API—since it’s the preferred way to interact with Marketing Cloud. /Les exemples de cette unité utilisent l’API REST, car c’est le moyen préféré d’interagir avec Marketing Cloud.
Create an Installed Package /Créer un package installé
Marketing Cloud uses installed packages to help authenticate users and API requests. /Marketing Cloud utilise des packages installés pour permettre l’authentification des utilisateurs et des appels API.
For this step, you need access to your Marketing Cloud account. (Contact your Marketing Cloud admin for help.) /Pour cette étape, il vous faut un accès à votre compte Marketing cloud. (Contacter votre administrateur Marketing cloud pour cela)
- In Marketing Cloud, go to Setup. /Dans Marketing Cloud, accédez à la configuration
- Click Apps. /Cliquez sur Apps
- Click Installed Packages. /Cliquez sur Packages installés
- Click New. /Cliquez sur Nouveau
- Give the package a name and description. /Donner un nom et une description au package
- Create the package with enhanced functionality. /Créer un package avec des fonctionnalités améliorées
- Save the package. /Enregistrer le package
- Under Components, click Add Component and select API Integration. /Sous Composants, cliquez sur Ajouter un composant et sélectionnez Intégration API.
9. Select an integration type. /Sélectionnez un type d’intégration.
- Server-to-Server with Client Credentials Grant Type /Serveur à serveur avec type d’attribution des informations d’identification client
- Web and Public App Integrations with Authorization Code Grant Type /Intégrations Web et applications publiques avec type d’autorisation de code d’autorisation
10-Set the integration properties, including scopes and the redirect URIs for web and public apps. /Définissez les propriétés d’intégration, notamment les étendues de services et les URI de redirection pour les applications Web et publiques.
Use https://127.0.0.1:80/ as a valid redirect URI for local testing. /Utilisez https://127.0.0.1:80/ comme URI de redirection valide pour les tests locaux.
11-Save the component. /Enregistrer le composant
Discover Your Endpoints / Découvrez vos points de terminaison
As we mentioned earlier, our APIs use tenant-specific endpoints. /Comme mentionné précédemment, nos API utilisent des points de terminaison spécifiques au locataire
That means, instead of directing all requests to a single endpoint, your endpoints include a subdomain unique to your tenant. /Cela signifie qu’au lieu de diriger toutes les demandes vers un seul point de terminaison, vos points de terminaison incluent un sous-domaine unique à votre locataire.
This also improves performance for your API requests by reducing the amount of traffic on any one endpoint. /Cela améliore également les performances de vos demandes d’API en réduisant la quantité de trafic sur n’importe quel point de terminaison.
Faster and more secure—that’s a win-win. /Rapide et plus sécurisé, c’est du gagnant-gagnant.
Your Marketing Cloud account contains the information you need to implement your endpoints. /Votre compte Marketing Cloud contient les informations dont vous avez besoin pour implementer vos points de terminaisons.
If you can’t directly access the account, contact your Marketing Cloud admin for the information you need to get started. /Si vous n’avez pas accès au compte, contacter votre Admin Marketing Cloud afin d’obtenir les informations dont vous avez besoin pour commencer.
Server-to-Server Integrations /Intégrations de serveur à serveur
Use server-to-server integrations to set up REST or SOAP API interactions between Marketing Cloud and your system. /Utilisez des intégrations de serveur à serveur pour configurer les interactions d’API REST ou SOAP entre Marketing Cloud et votre système.
You can set up your integration in just three steps. /Vous pouvez configurer votre intégration en seulement trois étapes.
Step 1—Request an access token using a client ID and secret. /Demander un jeton d’acces à l’aide d’un ID client et secret.
Installed packages generate these values for you when you create the integration. /Les packages installés génèrent ces valeurs pour vous quand vous créez l’intégration.
This example shows the information included in this REST API request. /Cet exemple montre les informations incluses dans cet appel REST API.
Store your client ID and secret securely. /Stockez votre identifiant client et secret en toute sécurité.
Never expose this information on the client side via JavaScript and don’t store it in a mobile application. /N’exposez jamais ces informations côté client via JavaScript et ne les stockez pas dans une application mobile.
Host: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com
POST /v2/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "7a9j47upktedde30uedl822p",
"client_secret": "1955278925675241571",
"scope": "email_read email_write email_send",
"account_id": "12345"
}
Step 2—Marketing Cloud returns an access token. /Marketing Cloud renvoie un jeton d’accès.
Extract this token for your use. /Extrayez ce jeton pour votre usage.
Give this token the same care and protection that you do for a username and password. /Donnez à ce jeton le même soin et la même protection qu’un nom d’utilisateur et mot de passe.
In other words, don’t post it on a public message board or leave it on an unencrypted document in your system. /En d’autres termes, ne le postez pas sur un objet public et ne le laissez pas sur un document non chiffré de votre système.
HTTP/1.1 200 OK
{
"access_token":"eyJhbLciOiJIPzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjIifQ.eyJhY2Nlc3NfdG9rZW4iOiJhYmJUQTlpSHZqRjkyd3Jkb0xWZEFCaloiLCJjbGllbnRfaWQiOiI3ZTRmYW1xaWUzcWtzdzlhNDRrcmxvZDgiLCJlaWQiOjEwNzU3Njc2LCJzdGFja19rZXkiOiJRQTFTMSJ9.wSFfEdeNrkoiU_tnmJ2ihm8iUqnJKlZoI3GlavTGBhs.hU4EsiC1e9txh_TCt90YlI2l7xZZ5E6_oa0xku3Jj9CCk1B72M4bhO3kUIyhwfVuB0MFbL0y9KD_RRFzg-nuqPgjPyONnby-iWopdZPBHd-3woupxCMST5-vfJO9qAED9qiUfYLS4WmHRuJTCX4NPScyu8BdROTVEe-D3iAoAeFoJX_rLZ9d5eEhIn1AvkYgoj9siuxAprHEvmySTgNIXkQA6uT_IQ-H1dbfOyJmlFKpYzvhvHb0KH7NJ24zy5bd2MQ5",
"expires_in":1200,
"token_type":"Bearer",
"rest_instance_url":"mc563885gzs27c5t9-63k636tzgm.rest.marketingcloudapis.com",
"soap_instance_url":"mc563885gzs27c5t9-63k636tzgm.soap.marketingcloudapis.com",
"scope": "email_read email_write email_send"
}
Step 3—Access your REST and SOAP API resources. /Accédez à vos ressources API REST et SOAP.
You’re good to go! Start planning and writing your requests. /Vous êtes prêt à partir! Commencez à planifier et à rédiger vos requetes.
Web and Public Integrations /Web et intégrations publiques
Use this method to allow a specific user to access your app using authorization from Marketing Cloud. /Utilisez cette méthode pour autoriser un utilisateur spécifique à accéder à votre application en utilisant l’autorisation de Marketing Cloud.
A web app can securely store a client secret, but a public app cannot. /Une application Web peut stocker en toute sécurité un secret client, mais pas une application publique.
Step 1—Redirect the User Web Browser to Marketing Cloud. /Redirigez le navigateur Web de l’utilisateur vers Marketing Cloud.
Include code in your app to perform the redirect to the Marketing Cloud authorization URL for your integration. Take a look at this example. /Incluez du code dans votre application pour effectuer la redirection vers l’URL d’autorisation Marketing Cloud pour votre intégration. Jetez un oeil à cet exemple.
https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com/v2/authorize?response_type=code&client_id=vqwyswrlzzfk024ivr682esb&redirect_uri=https%3A%2F%2Fwww.example.com%2Fcode_callback.jsp&scope=email_read%20email_write%20email_send&state=mystate
Step 2—Extract the authorization code. /Extraire le code d’autorisation.
A successful authorization returns a response containing an authorization code. Extract that code from the response, which appears like this. /Une autorisation réussie renvoie une réponse contenant un code d’autorisation. Extrayez ce code de la réponse, qui apparaît comme ceci.
https://www.example.com/code_callback.jsp?state=mystate&tssd={YOUR_MARKETING_CLOUD_SUBDOMAIN}
&code=aWekysIEeqM9PiThEfm0Cnr0MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w
Step 3—Request a token. /Demandez un jeton.
The request for the token looks like this. /La demande de jeton ressemble à ceci.
Host: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com
POST /v2/token
Content-Type: application/json
{
"grant_type": "authorization_code",
"code":
"eyJhbZciOiJIUzI1NiIsImtpZCI6IjIiLCJ2ZXIiOiIxIiwidHlwIjoiSldUIn0.eyJhY2Nlc3NfdG9rZW4iOiJhY0tlbEVIaTdzVERNNWd5VVR1VGdsS1YiLCJjbGllbnRfaWQiOiJmaG0yd2lsb2d2ajhqNXdzcWprZmgwejUiLCJlaWQiOjEwNzcxNzA2LCJzdGFja19rZXkiOiJRQTFTMSIsInBsYXRmb3JtX3ZlcnNpb24iOjIsImNsaWVudF90eXBlIjoiU2VydmVyVG9TZXJ2ZXIifQ.Q0qyABvInOiz3PfGsTDbj1coVTTdD8A4pCZS395P3Qo.DoROxfr3CQlMVMtVd5gYERWFYWoiNWojKObHxOq_5BqR98CDSAqfExfH-mv3PFMzy0U2NntttdgZK5wTL0UejXCxxH_XlcgL5k1TWzv_K-uTlPmliK2eI0LnaR1ti-TSqG36RnfUWzZ8KlAuGlqdGv-wgJtLeQTCEqE97yuqnlppgLLOB",
"client_id": "7a8j47upktedde30uedl822p",
“client_secret: “lYkAjPxnmHP4Zarpv1U4cLf0”
"redirect_uri": "http://www.example.com/code_callback.jsp/",
"scope": "email_read email_write email_send offline"
}
That request prompts Marketing Cloud to return the token. Again, take the utmost care to protect this token. /Cette demande invite Marketing Cloud à renvoyer le jeton. Encore une fois, prenez s’en grand soin de protéger ce jeton.
HTTP/1.1 200 OK
{
"access_token":"eyJhbZciOiJIUzI1NiIsImtpZCI6IjEiLCJ2ZXIiOiIxIiwidHlwIjoiSldUIn0.eyJhY2Nlc3NfdG9rZW4iOiJjZ3RHRklkUjUydnY4WHhLRHZaTDU2VHAiLCJjbGllbnRfaWQiOiI5b2xhcnI3emEyZHplaWtlaTBxZ2Z0dm0iLCJlaWQiOjEwODU1ODQsInN0YWNrX2tleSI6IlFBM1MxIiwicGxhdGZvcm1fdmVyc2lvbiI6MiwiY2xpZW50X3R5cGUiOiJDb25maWRlbnRpYWwifQ.Hp6gLSnlvBsx9FI6qXwJ12HJVzStWLIJdlzrx4XIIN4.t2kCu9YBNHVask49MQZXMlKGvYMXEc50QkRTc3y5_ylEWC8hPyEkU9sIanqL0ALSwFNyhQmMF6aajnmSrsD5obIl-NjXNfIwYWmnDqZU6HFBgbMoR3ofuEGIhrGokqUbD8nHZtgp-otgQSOg5Qj_RqUHUC0N0Fo4BUCXTq5BiM_EjP_djIKZF",
"refresh_token":"eyJhbZciOiJIUzI1NiIsImtpZCI6IjEiLCJ2ZXIiOiIxIiwidHlwIjoiSldUIn0.eyJyZWZyZXNoX3Rva2VuIjoiY2JINUE0aUdnTnBQVmJzOTlCUlZnNmh6IiwiY2xpZW50X2lkIjoiOW9sYXJyN3phMmR6ZWlrZWkwcWdmdHZtIiwiZWlkIjoxMDg1NTg0LCJzdGFja19rZXkiOiJRQTNTMSIsInBsYXRmb3JtX3ZlcnNpb24iOjIsImNsaWVudF90eXBlIjoiQ29uZmlkZW50aWFsIn0.-kScEfPhdz2g75b-KgTnmYKK9YTbUu9m9AhDTKkYFr4.mFd_EyLlPeAmfmwqqiBi_0HrAL5Ndtj1R9zWMj0Y80FOjB9n_EPYR0nKGKkNeijVuxmdMNgnOSF_isxGDwqjDoor2x4B-gP9Erl0gl4u58yzAXcjesNoJ1L96HJ3kjg-Jwke4p4K1MEWoB0fsrbDUaIAkg2Tf5THwrTLAxKRhn-ANltUDwUt",
"expires_in":1200,
"token_type":"Bearer",
"rest_instance_url":"mc563885gzs27c5t9-63k636tzgm.rest.marketingcloudapis.com",
"soap_instance_url":"mc563885gzs27c5t9-63k636tzgm.soap.marketingcloudapis.com",
"scope": "email_read email_write email_send"
}
Step 4—Access your REST and SOAP API resources. /Accédez à vos ressources API REST et SOAP.
Once you have your tokens in place, you’re ready to implement some REST or SOAP API requests! / Une fois vos jetons en place, vous êtes prêt à implémenter quelques demandes d’API REST ou SOAP!
Now that you can securely access both of the APIs, let’s take a closer look at each one. First up: the REST API. /Maintenant que vous pouvez accéder en toute sécurité aux deux API, voyons chacune de plus près. Tout d’abord : l’API REST.
Resources /Ressources
