Orders API 的最佳做法

本部分介绍的一些技巧可以帮助您更轻松地使用 Shopping Content API 库。

此外，GitHub 上托管的示例还具有演示 Orders API 的新功能。这些示例以“Orders”为前缀。

服务帐号密钥

在设置 Google 服务帐号时，您创建了一个密钥文件，并下载 JSON 文件。请妥善保存此文件。如果丢失，则无法重新下载。

某些 Google 库 API 直接使用此密钥文件，因此无需进行任何修改。

但是，如果您计划通过 Web 服务对 Orders API 执行 REST 调用，则必须修改此密钥文件中 private_key 字段的值：

移除 private_key 字段中的所有“\n”字符。
移除 private_key 字段末尾的所有“=”（等号）或“\u003d”（编码等号）值（如果存在）。

以下示例突出显示要移除的“=”和“\n”：

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

.NET

本部分为在 .NET 中实现 Orders API 的开发者提供了提示。

下载内容

从以下位置下载 .NET 资源：

OAuth

利用 OAuth 2.0 客户端 ID 和客户端密钥，大多数 Google 文档和示例都使用 .NET 进行显示。但是，此客户端 ID 无法作为已获授权的 Google 线上消费管理员添加到 Merchant Center，并且无法下载订单信息。

您应该用 Google 服务帐号。Google 服务帐号包含一个电子邮件地址，该地址可以添加到 Merchant Center 并且获得 Shopping Actions 权限。为了使用 Google 服务帐号，包含 Google 服务帐号凭据的 JSON 文件需要通过您的代码传递给 Google 以进行身份验证。

示例代码的 Authenticator.cs 文件支持传递 Google 服务帐号 JSON 文件，以进行身份验证。

沙盒与生产环境模式

为了获得沙盒和生产环境实例，您需要调用不同的端点。

要调用这些不同的端点，您需要使用 nuget 导入两个不同的库：

沙盒（开发/测试）：Google.Apis.ShoppingContent.v2sandbox
生产环境：Google.Apis.ShoppingContent.v2

您可以同时安装这两个库，因为这两个库具有不同的软件包层次结构。

然而，在两者之间切换的唯一方式是更改您的 import 语句。

Python

本部分为在 Python 中实现 Orders API 的开发者提供了提示。

下载内容

从以下位置下载 Python 资源：

OAuth

Python 库要求服务帐号的私钥包含换行符（“\n”），这些换行符包含在 JSON 文件中。如果要将凭据存储在单独的文件中，请务必在新文件中包含此密钥的换行符。

Java

本部分为在 Java 中实现 Orders API 的开发者提供了提示。

下载内容

从以下位置下载 Java 资源：

教程：编译和执行 GitHub Java 示例

本部分将引导您在 GitHub 代码库中编译和执行 Orders API Java 示例：

准备工作
第 1 步：安装和配置工具
第 2 步：加载商家信息和 Google oauth2.Credentials
第 3 步：使用 Maven 编译和包装项目
第 4 步：执行 OrdersWorkflow CLI

准备工作

要执行本教程，您必须完成以下准备工作：

关联 Google 服务帐号：按照 Orders API 使用入门，创建一个 Google 服务帐号 (GSA)，并将其关联至您的 Merchant Center 帐号。
下载密钥：在您创建 GSA 后，凭据会自动下载为 JSON 文件。
安装工具：为您的平台安装 javac、Maven 和 git。
下载示例：从 GitHub 代码库中下载 Google 示例。

您可以下载归档文件或克隆代码库。请注意，建议克隆代码库，以便使用 git diff 轻松查看所做的任何更改。例如：
```
$ git clone https://github.com/googleads/googleads-shopping-samples.git
```
clone 命令会提取所有示例，但您应该关注以下目录中此练习的 Java 订单示例源代码：
```
googleads-shopping-samples/java/src/shopping/v2/samples/orders/
```

第 1 步：安装和配置工具

如果您的开发者箱中尚未安装 Java 编译器和 Maven，请使用此部分中的信息。

根据您的平台安装 javac、Maven 和 git。如果您使用的是基于 Debian 的 Linux 发行版，则可以使用 apt‑get。

对于 Mac OS，您可以在终端中输入 javac 或 git。Mac OS 将建议获取它们的位置。您可以从 Apache Maven 网站获取 Maven。

要查看您是否已安装 Maven，请输入以下命令：

$ mvn --version

默认的 Maven 本地代码库位于您的主目录下：${user.home}/.m2/repository。要将此目录更改为另一个目录，请修改 ${MAVEN_HOME}/conf/settings.html 文件，并将 <localRepository> 更改为指向一个新位置。

第 2 步：加载商家信息和 Google oauth2.Credentials

将 merchant-info.json 文件复制到您的主目录。此文件位于 googleads-shopping-samples/ 中 GitHub 代码库的顶部。例如：
```
$ mkdir -p  ~/shopping-samples/content
$ cp ../merchant-info.json ~/shopping-samples/content/
```
修改 merchant-info.json 文件的本地副本：
1. 将 merchantId 的值替换为您的商家 ID。
2. 将电子邮件地址设置为空字符串。如果设置了电子邮件地址，则不会使用 GSA 的 JSON 密钥文件。
此文件内容应如下所示：
```
{
  "merchantId": your_merchant_ID,
  "accountSampleUser": "",
  "accountSampleAdWordsCID": 0,
  "emailAddress": ""
}
```
将 GSA 的密钥文件复制到示例类所需的位置。您之前下载过此 JSON 文件，是 Orders API 使用入门的一部分。

例如：
```
$ cp your_gsa_file.json ~/shopping-samples/content/service-account.json
```

第 3 步：使用 Maven 编译和包装项目

使用 Maven 编译项目。例如：

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

这也会下载项目的依赖项中定义的 Google API。

如果在依赖项下载过程中出现任何错误，请重试。某些 Maven 代码库可能会超时或出现其他错误。

要清理已编译的源代码，请使用 mvn clean。

编译成功后，Maven 在顶级项目目录中创建了一个 JAR 文件。例如：

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

第 4 步：执行 OrdersWorkflow CLI

执行 OrdersWorkflow CLI。例如：

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

如果在“为商家列出未确认的订单”过程中，OrdersWorkflow CLI 执行失败，请修改源文件 (java/src/main/java/shopping/content/v2/samples/orders/OrdersWorkflow.java)：

注释掉列出未确认订单的部分。以下示例显示了要注释掉的部分：

为 placedDateStart 参数指定一个新值，从而限制 list 方法的结果数。

您可以使用以下差异来修补 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();
   }

保存对 OrdersWorkflow.java 文件的更改后，重新编译并执行 CLI：

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

以下示例显示了成功执行的输出内容：

[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] ------------------------------------------------------------------------

获取访问令牌

要使用 RESTful 服务请求访问 Google 的 API，您的应用必须使用 OAuth 2.0 访问令牌向 Google 证明身份。

通过向 Google 的身份验证服务发送 JSON 网络令牌 (JWT)，您可以获得访问令牌。该服务会返回的访问令牌的最长有效时间为 60 分钟。您必须定期调用身份验证服务，并交换 JWT 以获得有效的访问令牌。

获得访问令牌后，将 RESTful 服务请求中的此访问令牌传递给 Orders API。

要获取和使用访问令牌，请执行以下操作：

配置您的 Google 控制台项目，以获取 GSA 的 JSON 密钥文件，如 Orders API 使用入门中所述。
从密钥文件中提取 client_email 和 secret_key 值。您将使用这些值来创建 JSON 网络令牌 (JWT)。

移除换行符、等号和字符串的其他部分，如服务帐号密钥中所述。
创建一个 JWT。传递作为 OAuth 调用一部分的 JWT，以在下一步中获取访问令牌。

JWT 由以下部分组成：
```
{header}.{claim_set}.{signed_signature}
```
JWT 的所有部分都是 base-64 网址编码。

header 定义算法和令牌类型，将其设置为以下值：
```
{
  "alg":"RS256",
  "typ":"JWT"
}
```
claim_set 包含有关身份验证请求的详情。定义声明集时，请使用以下格式：
```
{
  "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
}
```
其中：
- iss：服务帐号电子邮件地址，作为 Orders API 使用入门的一部分而创建。此电子邮件地址以“@developer.gserviceaccount.com”结尾。
- scope：指定哪些 API 正在获得授权。对于 Orders API，请使用“https://www.googleapis.com/auth/content”。您可以向多个 API 授权，可以用空格分隔这些 API。
- exp：JWT 的到期时间，以秒为单位，最早时间为 1970 年 1 月 1 日。JWT 的最长有效期是 1 小时，从当时的时间开始算。
- iat：当前时间。以秒为单位，最早时间为 1970 年 1 月 1 日。
signed_signature 是您的私钥的 RSA 已加密值（在第 2 步的 secret_key 值）。要对您的密钥进行签名，请在输入内容的 UTF-8 表示法中使用 SHA256withRSA（也称为 RSASSA-PKCS1-V1_5-SIGN，使用 SHA-256 哈希函数）。签名流程的输出内容将是一个字节数组。
提示：如果您使用 JWT.io 等库来创建 JWT，请执行以下操作：
- 将算法切换到 RS256。
- 在“签名”部分中，将“公钥”部分留空。
- 对于“私钥”，请包含私钥的“–––––BEGIN PRIVATE KEY–––––”和“–––––END PRIVATE KEY–––––”部分。
请注意，Google 的授权仅支持使用 SHA-256 哈希算法来加密您的签名（在标头中用 alg 的“RSA256”值来表示）。

组合标头、声明集和签名可能如下所示：
```
ewogICJhbGciOiJSUzI1NiIsCiAgInR5cCI6IkpXVCIKfS4KewogICJpc3MiOiJleGF
tcGxlQGRldmVsb3Blci5nc2VydmljZWFjY291bnQuY29tIiwKICAic2NvcGUiOiJodHRwczovL3d3dy5nb29nbGV
hcGlzLmNvbS9hdXRoL2NvbnRlbnQiLAogICJhdWQiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20vby9vYXV
0aDIvdG9rZW4iLAogICJleHAiOjE1MDg4NTc3OTYsCiAgImlhdCI6MTUwODg2MTM5Ngp9LgpaR1poYTJ4cVpIVTR
PVFExTkd3dWFXbzFPVEJ6WkhWblptRnBielE1TUhWVFZFVmtabXN1YkdwRVJreExSRFF5VTFORVJrZExURXBUCkN
tbHFOVGt3YzJSMVoyWmhhVzgwT1RCMVUxUkZaR1pyUldSbWF5NXNha1JHVEV0RU5ESlRVMFJHUjB0TVNsTlRSREl
5TXpNd05FUmgKTUFwa1ptRnJiR3BrZFRnNU5EVTBiQzVwYWpVNU1ITmtkV2RtWVdsdk5Ea3dkVk5VUldSbWF5NXN
ha1JHVEZOR09UQTBNZz09
```
在下一步中，您会将该值用作 JWT_encoded_message。
对 https://accounts.google.com/o/oauth2/v2/auth 执行 OAuth 调用，以申请访问令牌。在请求正文中，将 JWT 添加为 assertion 的值，如以下示例所示：
```
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"
```
您可以从发现文档获取最新版的 OAuth 端点和其他详情。
从响应中提取访问令牌的值。现在，您在请求中使用此令牌的时间最长为 60 分钟。
使用访问令牌向 Orders API 发送 RESTful 请求。为此，您可以将此令牌作为 access_token 查询字符串参数附加在后面，如以下示例所示：
```
orders_api_endpoint?access_token=auth_token
```
例如：
```
https://www.googleapis.com/content/v2sandbox/42/testordertemplates/template1?access_token=dkljsdf3jdfsk42
```
请注意，访问令牌的有效时间为 60 分钟。规定时间过后，您需要发出新的 OAuth 调用，以获取新的访问令牌（重复第 3 步至第 5 步）。在第 3 步中，请务必更新声明集中的当前时间和有效期，这将更改您发送的 JWT。

Google 的 OAuth 2.0 实现需要符合 OpenID Connect 规范，并且获得 OpenID 认证。如需其他详情并查看示例，请参阅 OpenID Connect。