Learning Objectives /Objectifs de formation
After completing this unit, you’ll be able to: /Une fois cette unite terminée, vous pourrez :
- Work with the methods, objects, and endpoints of the SOAP API. /Travaillez avec les méthodes, les objets et les points de terminaison de l’API SOAP.
- Configure a basic email message in Marketing Cloud. /Configurez un e-mail de base dans Marketing Cloud.
- Know when to use synchronous and asynchronous processing. /Sachez quand utiliser le traitement synchrone et asynchrone.
When Should You Use the SOAP API?/Quand devez-vous utiliser l’API SOAP?
While the REST API applies to many Marketing Cloud apps, the SOAP API focuses specifically on integrating with Email Studio. / Alors que l’API REST s’applique à de nombreuses applications Marketing Cloud, l’API SOAP se concentre spécifiquement sur l’intégration avec Email Studio.
Which means you can create, send, and retrieve tracking information on email messages—all using the SOAP API. /Ce qui signifie que vous pouvez créer, envoyer et récupérer des informations de suivi sur les e-mails, le tout à l’aide de l’API SOAP.
Plus, this API also permits changes to account information. /De plus, cette API permet également de modifier les informations de compte.
Read on for more about working with Email Studio and legacy integrations in Marketing Cloud. /Lisez la suite pour en savoir plus sur l’utilisation d’Email Studio et les intégrations héritées dans Marketing Cloud.
SOAP API Basics /Principes de base de l’API SOAP
The SOAP API authenticates using OAuth access tokens. / L’API SOAP s’authentifie à l’aide de jetons d’accès OAuth.
Remember this from earlier? / Nous en avons parlé plus tôt, t’en souviens-tu?
FYI, you can also authenticate with a UsernameToken created with a Marketing Cloud username and password, but the OAuth token provides a more secure connection. / Pour info, vous pouvez également vous authentifier avec un jeton Username créé avec un nom d’utilisateur et un mot de passe Marketing Cloud, mais le jeton OAuth fournit une connexion plus sécurisée.
The SOAP API also uses tenant-specific endpoints for both the WSDL and the endpoint. / L’API SOAP utilise également des points de terminaison spécifiques au locataire pour le WSDL et le point de terminaison.
You can use these links to work with the provided methods and objects. /Vous pouvez utiliser ces liens pour travailler avec les méthodes et objets fournis.
Marketing Cloud also provides legacy endpoints if you’re working on existing implementations, but it’s best to use the new endpoints for any new development. /Marketing Cloud fournit également des points de terminaison hérités si vous travaillez sur des implémentations existantes, mais il est préférable d’utiliser les nouveaux points de terminaison pour tout nouveau développement.
Methods and Objects / Méthodes et objets
Marketing Cloud provides several different methods you can use in your requests. / Marketing Cloud propose plusieurs méthodes différentes que vous pouvez utiliser dans vos demandes.
Your requests use these methods on different objects, such as Account, Email, Owner, and more. /Vos demandes utilisent ces méthodes sur différents objets, tels que compte, e-mail, propriétaire, etc
You can refer to the WSDL file or Salesforce Developers for a full list of available objects and properties. / Vous pouvez vous référer au fichier WSDL ou à la documentation Salesforce développeurs pour une liste complète des objets et propriétés disponibles.
Spoiler alert: There’s a bunch! Here are just a few. /. Attention: il y en a plein! En voici quelques-uns.
| Method Name | Purpose |
|---|---|
| Configure | Configure a Marketing Cloud account |
| Create | Create one or more objects |
| Delete | Delete one or more objects |
| Describe | Retrieve metadata for an object |
| Execute | Access and execute one or helper functions |
| Extract | Extract a file to the Marketing Cloud FTP site |
| GetSystemStatus | Retrieve the status of your Marketing Cloud account |
| Perform | Perform an asynchronous action |
| Query | Query Marketing Cloud data |
| Retrieve | Get information on a single object type |
| Schedule | Schedule an action or event to occur |
| Update | Update information on one or more objects |
Note /Remarque
Some objects or associated sub-objects are for internal use only or reserved for future use. / Certains objets ou sous-objets associés sont destinés à un usage interne uniquement ou réservés pour une utilisation future.
Working with the SOAP API /Travailler avec l’API SOAP
When you work with the SOAP API, it’s helpful to keep a few things in mind. / Quand vous travaillez avec l’API SOAP, il est utile de garder quelques éléments à l’esprit.
- You can expect synchronous processing of your requests anywhere from 3 seconds (for a single email send) to 30 seconds (for retrieval of tracking data). / Vous pouvez vous attendre à un traitement synchrone de vos demandes allant de 3 secondes (pour un seul envoi de courrier électronique) à 30 secondes (pour la récupération des données de suivi).
- Each request returns one of three statuses. /Chaque demande renvoie l’un des trois statuts.
- OK
- Has Error
- Error
- Marketing Cloud stores data values in central standard time (CST) with no variation for daylight saving time. / Marketing Cloud stocke les valeurs des données en heure standard centrale (CST) sans variation de l’heure d’été. You can use a coordinated universal time (UTC) offset when retrieving date information to make sure that information is optimized for your system. /Vous pouvez utiliser un décalage d’heure universelle coordonnée (UTC) lors de la récupération des informations de date pour vous assurer que les informations sont optimisées pour votre système.
- You can set different character sets for email messages depending on the culture codes you send to, so it’s a good idea to test these messages to make sure all characters appear correctly. /Vous pouvez définir différents jeux de caractères pour les e-mails en fonction des codes de culture auxquels vous envoyez, c’est donc une bonne idée de tester ces messages pour vous assurer que tous les caractères apparaissent correctement.
Example: Create an Email Message /Exemple: créer un e-mail
Let’s take a look at some common SOAP API tasks. This C# example shows how to create a simple email. / Voyons quelques tâches courantes de l’API SOAP. Cet exemple C # montre comment créer un simple e-mail.
The code assigns a subject line and content, and an identifying name and location, so you can easily find it in your Marketing Cloud account. /Le code attribue une ligne d’objet et un contenu, ainsi qu’un nom et un emplacement d’identification, afin que vous puissiez facilement les trouver dans votre compte Marketing Cloud.
Email email = new Email();
email.Subject = "Check out my way cool email";
email.Name = "Dynamic Email_" + DateTime.Now.ToShortTimeString();
email.HTMLBody = "<center>##Way Cool Email</center>";
email.TextBody = "Way Cool Email";
email.CharacterSet = "iso-8859-1";
email.CategoryID = 556442; //This is the Folder where the email is stored.
email.CategoryIDSpecified = true;
CreateResult[] results = proxy.Create(new CreateOptions(), new APIObject[] { email }, out requestID, out status);
This next C# example shows one way to send an email message with an email send definition. That send definition includes the information you need to identify the email sent and any additional send details. /Cet exemple C # suivant montre une façon d’envoyer un e-mail avec une définition d’envoi d’e-mail. Cette définition d’envoi comprend les informations dont vous avez besoin pour identifier l’e-mail envoyé et tout détail d’envoi supplémentaire.
// 1. Create the EmailSendDefinition
EmailSendDefinition sd = new EmailSendDefinition();
sd.CustomerKey = "95";
// 2. Start the Send
PerformResult[] results = integrationFramework.Perform(new PerformOptions(), "start", new InteractionBaseObject[] { sd }, out status, out message, out requestID);
// 3. Print out overall results
System.Text.StringBuilder sb = new System.Text.StringBuilder();
sb.Append("Perform Send Definition");
sb.AppendFormat("\nOverall result: {0}. RequestID: {1}, {2}\n{3}\n{4}\n{5}\nTaskID: {6}", status, requestID, message, results[0].ErrorCode, results[0].StatusCode, results[0].StatusMessage, results[0].Task.ID);
Console.WriteLine(sb.ToString());
After the send completes, you can retrieve tracking information on the send using this sample code. (Just remember, you need to include the JobID returned after the original send.) /Une fois l’envoi terminé, vous pouvez récupérer des informations de suivi sur l’envoi à l’aide de cet exemple de code. (N’oubliez pas, vous devez inclure le JobID retourné après l’envoi d’origine.)
/**
*Returns details of send - when you send email, it returns JobID.
*Use returned ID to get details.
*/
public void testSendDetails()
{
RetrieveRequest retrieveRequest = new RetrieveRequest();
retrieveRequest.ObjectType = "Send";
String[] props = { "SentDate", "UniqueOpens", "NumberSent", "NumberDelivered", "HardBounces", "SoftBounces" };
retrieveRequest.Properties =props;
/**
* Use date range to get all sends that happened in range
*/
/**
SimpleFilterPart filter = new SimpleFilterPart();
filter.Property = "SendDate";
filter.SimpleOperator = SimpleOperators.greaterThanOrEqual;
filter.DateValue = new DateTime[1];
filter.DateValue[0] = DateTime.Now;
retrieveRequest.Filter = filter;
*/
/**
* Details for the particular job
*/
SimpleFilterPart filter = new SimpleFilterPart();
filter.Property = "ID";
filter.SimpleOperator = SimpleOperators.equals;
filter.Value= new string[] {"12043295"};
retrieveRequest.Filter = filter;
/**
* If this job happened from Child Account include ClientId in request.
*/
/*
ClientID id = new ClientID();
id.ID = 90554;
id.IDSpecified = true;
retrieveRequest.ClientIDs = new ClientID[] {id};
*/
APIObject[] results = null;
String requestId = null;
String response = soapClient.Retrieve(retrieveRequest, out requestId, out results);
Send send = null;
if (response != null && response.ToLower().Equals("ok"))
{
if (results != null)
{
send = (Send) results[0];
}
}
Assert.IsNotNull(send);
}
Most API objects return results in batches of 2,500. You can ask for smaller batches in your requests, or you can perform additional requests to retrieve results with more than 2,500 records. /La plupart des objets API renvoient des résultats par lots de 2 500. Vous pouvez demander des lots plus petits dans vos demandes, ou vous pouvez effectuer des demandes supplémentaires pour récupérer les résultats avec plus de 2 500 enregistrements.
Synchronous and Asynchronous Processing / Traitement synchrone et asynchrone
You can choose to perform your requests as synchronous or asynchronous operations. / Vous pouvez choisir d’effectuer vos demandes en tant qu’opérations synchrones ou asynchrones.
Synchronous calls achieve almost immediate results. /Les appels synchrones obtiennent des résultats presque immédiats.
The SOAP API queues asynchronous operations to ensure that your calls don’t get lost if the service becomes unavailable. /L’API SOAP met en file d’attente les opérations asynchrones pour garantir que vos appels ne seront pas perdus si le service devient indisponible.
Use asynchronous processing to ensure more resilient requests to the SOAP API. / Utilisez un traitement asynchrone pour garantir des demandes plus résilientes à l’API SOAP.
This method protects against dropped requests in case of a system outage and queues your requests for more predictable performance. / Cette méthode protège contre les demandes abandonnées en cas de panne du système et met vos demandes en file d’attente pour des performances plus prévisibles.
We also recommend making only 20 or fewer synchronous API calls per hour. / Nous vous recommandons également d’effectuer seulement 20 appels API synchrones ou moins par heure.
Those calls should include references for up to 50 objects per synchronous call or 100 objects per asynchronous call. /Ces appels doivent inclure des références pour un maximum de 50 objets par appel synchrone ou 100 objets par appel asynchrone.
Stick around—the next unit gives you expert tips and resources to make the most of your API integrations. / Continuez- l’unité suivante vous donne des conseils d’experts et des ressources pour tirer le meilleur parti de vos intégrations d’API
Resources /Ressources
