Bonnes pratiques

Cette section décrit certaines techniques qui peuvent faciliter l'utilisation des bibliothèques Content API for Shopping.

De plus, les exemples hébergés sur GitHub disposent d'une nouvelle fonctionnalité permettant de tester la ressource Orders. Ces exemples sont précédés de "Orders".

Clé de compte de service

Lors de la configuration de votre compte de service Google, vous avez créé un fichier de clé que vous avez téléchargé sous la forme d'un fichier JSON. Ne le perdez pas. Si jamais vous l'égarez, vous ne pourrez pas le télécharger à nouveau.

Certaines API de la bibliothèque Google utilisent directement le fichier de clé. Par conséquent, aucune modification n'est nécessaire.

Toutefois, si vous envisagez d'effectuer des appels REST à la ressource Orders via un service Web, vous devez modifier la valeur du champ private_key dans le fichier de clé :

Supprimez tous les caractères "\n" du champ private_key.
Supprimez toutes les valeurs "=" (signe égal) ou "\u003d" (signe égal encodé) à la fin du champ private_key, le cas échéant.

Voici un exemple de caractères "=" et "\n" à supprimer :

"private_key": "–––––BEGIN PRIVATE KEY––––– ... \n08875j5642fff...==\n–––––END PRIVATE KEY–––––\n"

.NET

Cette section fournit des conseils destinés aux développeurs qui implémentent la ressource Orders en .NET.

Téléchargements

Téléchargez les ressources .NET à partir des emplacements suivants :

OAuth

La plupart des documents et des exemples Google présentent l'utilisation de .NET avec un ID et une clé client OAuth 2.0. Toutefois, il est impossible d'ajouter l'ID client à Merchant Center en tant que responsable Shopping Actions autorisé, ou de télécharger les informations sur les commandes avec cet ID client.

À la place, vous devez utiliser un compte de service Google incluant une adresse e-mail pouvant être ajoutée à Merchant Center et disposant d'autorisations Acheter sur Google. Pour pouvoir utiliser un compte de service Google, votre code doit transmettre à Google le fichier JSON contenant les identifiants de ce compte, à des fins d'authentification.

Le fichier Authenticator.cs de l'exemple de code accepte la transmission du fichier JSON du compte de service Google pour l'authentification.

Modes Sandbox et de production

Vous devez appeler différents points de terminaison pour atteindre les instances sandbox et de production.

Pour ce faire, vous devez importer deux bibliothèques différentes à l'aide de nuget :

Sandbox (développement/test) : Google.Apis.ShoppingContent.v2sandbox
Production : Google.Apis.ShoppingContent.v2

Ces deux bibliothèques peuvent être installées simultanément, car elles ont des hiérarchies de packages différentes.

Malheureusement, la seule façon de basculer de l'une à l'autre est de modifier les instructions import.

Python

Cette section fournit des conseils destinés aux développeurs qui implémentent la ressource Orders en Python.

Téléchargements

Téléchargez les ressources Python à partir des emplacements suivants :

OAuth

La bibliothèque Python exige que la clé privée du compte de service contienne les sauts de ligne ("\n") présents dans le fichier JSON. Si vous stockez les identifiants dans un fichier distinct, veillez à inclure les sauts de ligne de la clé dans le nouveau fichier.

Java

Cette section fournit des conseils destinés aux développeurs qui implémentent la ressource Orders en Java.

Téléchargements

Téléchargez les ressources Java à partir des emplacements suivants :

Tutoriel : Compiler et exécuter des exemples Java GitHub

Cette section explique comment compiler et exécuter les exemples Java de la ressource Orders dans le dépôt GitHub :

Conditions préalables
Étape 1 : Installez et configurez les outils
Étape 2 : Chargez les informations sur le marchand et les identifiants Google OAuth 2
Étape 3 : Compilez le projet et créez un package à l'aide de Maven
Étape 4 : Exécutez la CLI OrdersWorkflow

Conditions préalables

Pour suivre ce tutoriel, vous devez respecter les conditions suivantes :

Associer le compte de service Google : suivez les instructions de la section Premiers pas avec la ressource Orders pour créer un compte de service Google et l'associer à votre compte Merchant Center.
Télécharger la clé : une fois que vous avez créé le compte, les identifiants sont automatiquement téléchargés sous la forme d'un fichier JSON.
Installer les outils : installez javac, Maven et git pour votre plate-forme.
Télécharger les exemples : téléchargez les exemples Google à partir du dépôt GitHub.

Vous pouvez télécharger l'archive ou cloner le dépôt. Sachez qu'il est préférable de cloner le dépôt pour que vous puissiez voir facilement les modifications que vous apportez à l'aide de git diff. Exemple :
```
$ git clone https://github.com/googleads/googleads-shopping-samples.git
```
La commande clone récupère tous les exemples, mais, pour cet exercice, vous devez vous concentrer sur les exemples de sources de commandes Java qui se trouvent dans le répertoire suivant :
```
googleads-shopping-samples/java/src/shopping/v2/samples/orders/
```

Étape 1 : Installez et configurez les outils

Si vous ne disposez pas déjà d'un compilateur Java et que Maven n'est pas encore installé dans votre Box de développement, utilisez les informations fournies dans cette section.

Installez javac, Maven et git en fonction de votre plate-forme. Si vous vous servez d'une distribution Linux basée sur Debian, vous pouvez utiliser apt‑get.

Pour macOS, vous pouvez saisir javac ou git dans le terminal, et macOS vous suggérera où trouver ces outils. Vous pouvez obtenir Maven sur le site Apache Maven.

Pour voir si Maven est déjà installé, saisissez la commande suivante :

$ mvn --version

Le dépôt local Maven par défaut se trouve sous votre répertoire d'accueil : ${user.home}/.m2/repository. Pour le placer dans un répertoire différent, accédez au fichier ${MAVEN_HOME}/conf/settings.html et indiquez un autre emplacement dans <localRepository>.

Étape 2 : Chargez les informations sur le marchand et les identifiants Google OAuth 2

Copiez le fichier merchant-info.json dans votre répertoire d'accueil. Ce fichier est situé en haut du dépôt GitHub dans googleads-shopping-samples/. Exemple :
```
$ mkdir -p  ~/shopping-samples/content
$ cp ../merchant-info.json ~/shopping-samples/content/
```
Modifiez la copie locale du fichier merchant-info.json :
1. Remplacez la valeur de merchantId par votre ID de marchand.
2. N'indiquez aucune valeur pour l'adresse e-mail. Si cette dernière est définie, le fichier de clé JSON du compte de service Google n'est pas utilisé.
Le fichier doit se présenter comme suit :
```
{
  "merchantId": your_merchant_ID,
  "accountSampleUser": "",
  "accountSampleAdWordsCID": 0,
  "emailAddress": ""
}
```
Copiez le fichier de clé du compte de service Google à l'emplacement attendu par les classes d'exemples. Vous avez téléchargé ce fichier JSON en suivant la procédure indiquée dans la section Premiers pas avec la ressource Orders.

Exemple :
```
$ cp your_gsa_file.json ~/shopping-samples/content/service-account.json
```

Étape 3 : Compilez le projet et créez un package à l'aide de Maven

Compilez le projet à l'aide de Maven. Exemple :

$ cd googleads-shopping-samples/java
$ mvn compile
$ mvn package

Cette action entraîne également le téléchargement des API Google, comme défini dans les dépendances du projet.

Si des erreurs se produisent lors du téléchargement des dépendances, réessayez. Certains dépôts Maven peuvent dépasser le délai ou rencontrer d'autres erreurs.

Pour nettoyer les sources compilées, exécutez mvn clean.

Une fois la compilation accomplie, Maven crée un fichier JAR dans le répertoire de projet de premier niveau. Exemple :

googleads-shopping-samples/java/target/OrdersWorkflow-v2-rev77-1.21.0.jar

Étape 4 : Exécutez la CLI OrdersWorkflow

Exécutez la CLI OrdersWorkflow. Exemple :

$ cd googleads-shopping-samples/java
$ mvn exec:java -Dexec.mainClass="shopping.v2.samples.orders.OrdersWorkflow"

Si l'exécution de la CLI OrdersWorkflow échoue à l'étape "Listing unacknowledged orders for merchant" (Récupération des commandes non confirmées pour le marchand), modifiez le fichier source (java/src/main/java/shopping/content/v2.1/samples/orders/OrdersWorkflow.java) :

Commentez la section qui répertorie les commandes non confirmées. L'exemple suivant montre la section à commenter :

Limitez le nombre de résultats générés par la méthode list en spécifiant une valeur récente pour le paramètre placedDateStart.

Vous pouvez vous servir de la différence suivante pour appliquer un correctif au fichier OrdersWorkflow.java :

--- a/java/src/shopping/v2/samples/orders/OrdersWorkflow.java
+++ b/java/src/shopping/v2/samples/orders/OrdersWorkflow.java
@@ -17,6 +17,9 @@ import java.io.IOException;
 import java.util.Random;
 import shopping.v2.samples.BaseSample;

+import java.util.Date;
+import java.text.SimpleDateFormat;
+import java.util.Calendar;
 /**
  * Sample that runs through an entire test order workflow. We run this sample on the sandbox
  * API endpoint, so that we have access to test order creation and don't accidentally mutate real
@@ -44,9 +47,14 @@ public class OrdersWorkflow extends BaseSample {
     System.out.println();

     // List the unacknowledged orders.
+    String orderDateStart = getOrderDateStart(); // default: Limit the list call to Yesterday's orders
+                                                 // modify this function to increase/decrease the limit.
+
     System.out.printf("Listing unacknowledged orders for merchant %d:%n", config.getMerchantId());
     ShoppingContent.Orders.List listCall = sandbox.orders().list(config.getMerchantId())
-        .setAcknowledged(false);
+        .setAcknowledged(false)
+       .setPlacedDateStart(orderDateStart)
+       ;
     do {
       OrdersListResponse page = listCall.execute();
       for (Order product : page.getResources()) {
@@ -233,6 +241,14 @@ public class OrdersWorkflow extends BaseSample {
     return ret;
   }

+  private String getOrderDateStart() {
+    Calendar cal = Calendar.getInstance();
+    cal.add(Calendar.DATE, -1); // Yesterday. Change this to -7 for a weeks worth of data.
+    String ret  = new SimpleDateFormat("yyyy-MM-dd").format(cal.getTime());
+    System.out.printf("Listing placed orders from date: \"%s\"... \n", ret);
+    return ret;
+  }
+
   public static void main(String[] args) throws IOException {
     new OrdersWorkflow().execute();
   }

Après avoir enregistré vos modifications dans le fichier OrdersWorkflow.java, recompilez et exécutez la CLI :

$ cd googleads-shopping-samples/java
  $ mvn compile
  $ mvn package
  $ mvn exec:java -Dexec.mainClass="shopping.v2.samples.orders.OrdersWorkflow"

L'exemple suivant montre le résultat généré en cas de succès de l'exécution :

[INFO] ------------------------------------------------------------------------
[INFO] [exec:java {execution: default-cli}]
Loaded the Application Default Credentials.
Creating test order... done.
Order "TEST-3907-38-6950" created.

Acknowledging order "TEST-3907-38-6950"... done with status "executed".

Updating merchant order ID to "test order -663546118768520962"... done with status "executed".

Retrieving order "TEST-3907-38-6950"... done.

Order "TEST-3907-38-6950":
- Status: inProgress
...
--

   1 of item "S3LIDLO54ICZEYE"

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 40 seconds
[INFO] Finished at: Tue Jan 03 19:13:32 EST 2017
[INFO] Final Memory: 21M/181M
[INFO] ------------------------------------------------------------------------

Obtenir un jeton d'accès

Pour accéder aux API de Google avec une requête de service RESTful, votre application doit s'identifier auprès de Google à l'aide d'un jeton d'accès OAuth 2.0.

Afin d'obtenir un jeton d'accès, envoyez un jeton Web JSON (JWT, JSON Web Token) au service d'authentification de Google, qui renvoie un jeton d'accès valable jusqu'à 60 minutes. Vous devez appeler régulièrement le service d'authentification et échanger le jeton JWT contre un jeton d'accès valide.

Après avoir obtenu un jeton d'accès, vous le transmettez dans vos requêtes de service RESTful à la ressource Orders.

Pour obtenir et utiliser un jeton d'accès :

Configurez votre projet de console Google de façon à obtenir le fichier de clé JSON du compte de service Google, comme décrit dans la section Premiers pas avec la ressource Orders.
Extrayez les valeurs client_email et secret_key du fichier de clé. Elles vous serviront à créer un JWT.

Supprimez les sauts de ligne, les signes "égal" et d'autres parties de la chaîne, comme décrit dans la section Clé de Service Account.
Créez un JWT. Vous le transmettrez dans le cadre de votre appel OAuth pour obtenir le jeton d'accès à l'étape suivante.

Un JWT se compose des parties suivantes :
```
{header}.{claim_set}.{signed_signature}
```
Toutes les parties du JWT font l'objet d'un encodage d'URL en base64.

La partie header définit l'algorithme et le type de jeton. Définissez-la comme suit :
```
{
  "alg":"RS256",
  "typ":"JWT"
}
```
La partie claim_set contient des détails sur la requête d'authentification. Utilisez le format suivant lorsque vous définissez votre ensemble de revendications :
```
{
  "iss":"SERVICE_ACCT_CLIENT_EMAIL_ADDRESS",
  "scope":"https://www.googleapis.com/auth/content",
  "aud":"https://accounts.google.com/o/oauth2/token",
  "exp":NOW_+1HR_TIME_IN_SEC_FROM_01-01-1970,
  "iat":NOW_TIME_IN_SEC_FROM_01-01-1970
}
```
Où :
- iss est l'adresse e-mail du compte de service que vous avez créé en suivant la procédure indiquée dans la section Premiers pas avec la ressource Orders. Il s'agit de l'adresse e-mail qui finit par @developer.gserviceaccount.com.
- scope indique les API qui sont autorisées. Pour la ressource Orders, utilisez "https://www.googleapis.com/auth/content". Vous pouvez autoriser plusieurs API en les séparant par une espace.
- exp est l'heure d'expiration du JWT, exprimée en secondes depuis le 1er janvier 1970. La durée de vie maximale d'un JWT est d'une heure à partir de MAINTENANT (NOW).
- iat est l'heure actuelle, exprimée en secondes depuis le 1er janvier 1970.
La partie signed_signature est une valeur chiffrée par RSA de votre clé privée (la valeur de secret_key définie à l'étape 2). Pour signer votre clé, servez-vous de SHA256withRSA (également appelé RSASSA-PKCS1-V1_5-SIGN avec la fonction de hachage SHA-256) sur une représentation UTF-8 de l'entrée. La sortie du processus de signature sera un tableau d'octets.
CONSEIL : Si vous créez le JWT à l'aide d'une bibliothèque telle que JWT.io, procédez comme suit :
- Changez l'algorithme en RS256.
- Dans la section "Signature", laissez vide la section "Clé publique".
- Pour la clé privée, utilisez les parties "–––––BEGIN PRIVATE KEY–––––" et "–––––END PRIVATE KEY–––––" de la clé privée.
Sachez que le processus d'autorisation de Google n'accepte que l'algorithme de hachage SHA-256 pour chiffrer la signature (comme indiqué par la valeur "RSA256" pour alg dans la partie header).

L'association de l'en-tête, de l'ensemble de revendications et de la signature peut se présenter comme suit :
```
ewogICJhbGciOiJSUzI1NiIsCiAgInR5cCI6IkpXVCIKfS4KewogICJpc3MiOiJleGF
tcGxlQGRldmVsb3Blci5nc2VydmljZWFjY291bnQuY29tIiwKICAic2NvcGUiOiJodHRwczovL3d3dy5nb29nbGV
hcGlzLmNvbS9hdXRoL2NvbnRlbnQiLAogICJhdWQiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20vby9vYXV
0aDIvdG9rZW4iLAogICJleHAiOjE1MDg4NTc3OTYsCiAgImlhdCI6MTUwODg2MTM5Ngp9LgpaR1poYTJ4cVpIVTR
PVFExTkd3dWFXbzFPVEJ6WkhWblptRnBielE1TUhWVFZFVmtabXN1YkdwRVJreExSRFF5VTFORVJrZExURXBUCkN
tbHFOVGt3YzJSMVoyWmhhVzgwT1RCMVUxUkZaR1pyUldSbWF5NXNha1JHVEV0RU5ESlRVMFJHUjB0TVNsTlRSREl
5TXpNd05FUmgKTUFwa1ptRnJiR3BrZFRnNU5EVTBiQzVwYWpVNU1ITmtkV2RtWVdsdk5Ea3dkVk5VUldSbWF5NXN
ha1JHVEZOR09UQTBNZz09
```
Vous utiliserez cette valeur en tant que JWT_encoded_message à l'étape suivante.
Effectuez un appel OAuth auprès de https://accounts.google.com/o/oauth2/v2/auth pour demander un jeton d'accès. Incluez le JWT comme valeur de assertion dans le corps de la requête, comme illustré dans l'exemple suivant :
```
POST https://accounts.google.com/o/oauth2/v2/auth
Content-type: application/x-www-form-urlencoded
Payload (Body):
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
  "assertion": "JWT_encoded_message"
```
Vous pouvez obtenir la dernière version du point de terminaison OAuth et d'autres détails dans le document de découverte.
Extrayez la valeur du jeton d'accès de la réponse. Vous pouvez maintenant utiliser ce jeton dans vos requêtes pendant une durée maximale de 60 minutes.
Envoyez une requête RESTful à la ressource Orders en incluant le jeton d'accès. Pour ce faire, ajoutez le jeton en tant que paramètre de chaîne de requête access_token, comme illustré dans l'exemple suivant :
```
orders_api_endpoint?access_token=auth_token
```
Exemple :
```
https://www.googleapis.com/content/v2.1sandbox/42/testordertemplates/template1?access_token=dkljsdf3jdfsk42
```
Sachez que le jeton d'accès est valable pendant 60 minutes. Passé ce délai, vous devrez émettre un nouvel appel OAuth pour obtenir un nouveau jeton d'accès (répétez les étapes 3 à 5). À l'étape 3, veillez à mettre à jour l'heure actuelle et l'heure d'expiration dans l'ensemble de revendications, ce qui modifiera le JWT que vous envoyez.

La mise en œuvre OAuth 2.0 de Google est conforme à la spécification OpenID Connect, et elle est certifiée OpenID. Pour obtenir plus de détails et d'exemples, consultez la page OpenID Connect.