企业对接Walmart平台API流程 On-request Reports API（二）

对接On-request Reports API

- 1、对接指南
- - 1.1 报告生成时间
  - 1.2 报告保留期
  - 1.3 请求限制
  - 1.4 报告请求工作流
  - 如何申请报告
  - - 第 1 步：申请取消报告
    - 第 2 步：获取报表可用性状态
    - 第 3 步：下载报告 URL
- 2、代码实现
- - 2.1、获取访问API的token
  - 2.2、构建公共请求方法
  - 2.3 编写demo测试创建报告API

1、对接指南

1.1 报告生成时间

请求报告后，需要 15 到 45 分钟才能生成，然后可供下载。

1.2 报告保留期

您请求的报告将保留 30 天。您可以使用报告的请求 ID 请求 30 天的报告，无需请求新的报告。

1.3 请求限制

您每小时可以为每种报告类型请求一份报告。虽然您可以同时请求多种报告类型，但每小时只能为每种报告类型发出一次请求。

1.4 报告请求工作流

使用创建报告请求 API 创建报告请求。对于每个请求，系统都会创建一个requestId，卖家可以使用该 ID 来跟踪所请求报告的状态。
使用报告请求状态 API 检查报告请求提交状态，该 API 返回有关报告状态的所有详细信息。
报表状态为READY后，您现在可以使用下载报表 URL API 下载报表。
（可选）：您还可以使用获取所有报告请求 API 获取所有报告请求的列表。
（可选）：如果使用创建订阅 API设置通知：当您收到报告已准备就绪的通知时，可以使用下载报表 URL API 检索它以供下载。

如何申请报告

第 1 步：申请取消报告

若要请求项目报告，请调用创建报告请求 API。

例如，调用v3/reports/reportRequests?reportType=REPORT-TYPE&reportVersion=v1

将REPORT-TYPE替换为您需要请求的报告类型。

指定所有必需参数的值：

reportType– 指定您要请求的报告（例如 reportType=CANCELLATION）。
reportVersion– 指定报告版本（例如 reportVersion=v1）。
成功后，API 调用将返回一个 requestId ，您可以使用它来了解报告是否已准备好下载，以及请求的状态（例如 RECEIVED或 INPROGRESS）。它还返回requestSubmissionDate， UTC 格式的值：YYYY-MM-DDTHH：mm：ssZ。

您还可以设置通知，以便在报告状态为 READY 时触发。要设置通知，请参阅通知。

第 2 步：获取报表可用性状态

若要了解报告是否已准备好下载，请调用报告请求状态 API 以检索报告请求状态。当状态为READY时，您可以下载报告。API 只能检索过去 30 天内创建的请求的详细信息。

例如，使用requestId进行调用。v3/reports/reportRequests?{requestId}

成功后，此调用将检索指定requestId的状态（例如 SUBMITTED、INPROGRESS、READY 或 ERROR）。

第 3 步：下载报告 URL

若要下载请求的报告，请调用下载报告 URL API”，并指定“由报告状态通知发送”或从报告请求状态 API 调用发送的“链接”。requestID

例如，调用/v3/reports/downloadReport?requestId={requestId}

成功后，您将收到用于下载报告的 URL 以及 URL 过期时间：

	downloadURL– 用于下载报告的 URL。
	downloadURLExpirationTime– 下载 URL 过期时间。

为避免错误，请务必检查以下情况是否不适用于您的请求：

请求已过期。在这种情况下，报告不再可用。
如果报告尚不可用，请检查状态是否为INPROGRESS。
可能是系统错误或数据错误。
如果无效。请确保您拥有正确的 requestId，或者它在 30 天后仍未过期。

2、代码实现

2.1、获取访问API的token

public static String getAccessToken(String appKey, String appSecret) {
        String authorization = getAuthorization(appKey, appSecret);
        Map<String, String> headers = new HashMap<>();
        headers.put("Authorization", authorization);
        headers.put("WM_SVC.NAME", "Shop name");
        headers.put("WM_QOS.CORRELATION_ID", IdUtil.randomUUID());
        HttpResponse response = HttpRequest
                .post("https://marketplace.walmartapis.com/v3/token")
                .addHeaders(headers)
                .body("grant_type=client_credentials", "application/x-www-form-urlencoded")
                .execute();
        JSONObject jsonObject = JSONUtil.parseObj(response.body());
        return jsonObject.getStr("access_token");
    }

2.2、构建公共请求方法

public static String request(Method method,
                                 String url,
                                 Map<String, Object> paramMap,
                                 String jsonBody) {

        String appkey = "xxxxxx-xxxxxxxx8cb";
        String appSecret = "AOqxxxxxxxxxxxxxxxxxxxxxxbo";
        String accessToken = getAccessToken(appkey, appSecret);

        //appkey和appSecret换成自己的
        Map<String, String> headers = getHeaders(method, accessToken);
        // get请求拼接参数
        if (paramMap != null && paramMap.size() > 0) {
            if (url.indexOf("?") > 0) {
                url = url + "&" + HttpUtil.toParams(paramMap);
            } else {
                url = url + "?" + HttpUtil.toParams(paramMap);
            }
        }
        HttpResponse resp;

        if (method == Method.POST) {
            resp = HttpRequest.post(url)
                    .addHeaders(headers)
                    .body(jsonBody)
                    .execute();

        } else if (method == Method.GET) {
            resp = HttpRequest.get(url)
                    .addHeaders(headers)
                    .execute();
        } else {
            String msg = "仅支持GET 和POST请求";
            log.error(msg);
            return msg;
        }

        if (HttpStatus.HTTP_OK == resp.getStatus()) {
            log.info("接口响应数据response.body()：{}", resp.body());
            return resp.body();
        } else {
            log.error("调用Walmart API 错误");
            return "调用Walmart API 错误";
        }
    }

2.3 编写demo测试创建报告API

 public static void main(String[] args) {


        String url = "https://marketplace.walmartapis.com/v3/reports/reportRequests";
        Map<String, Object> param = new HashMap<>();
        param.put("reportType", "ITEM");
        param.put("reportVersion", "v4");
        //1、把你想要展示到报告中的字段都可以往里面写
        //字段网址：https://developer.walmart.com/doc/us/mp/us-mp-onrequestreports/
        List<String> columns = Arrays.asList("SKU", "Item ID", "Product Name",
                "Price", "Lifecycle Status", "Publish Status", "Status Change Reason",
                "Average Rating", "Shelf Name");
        //2、添加过滤条件，这里以过滤 Publish Status = PUBLISHED为例子
        JSONObject statusFilter = new JSONObject();
        statusFilter.set("type", "enumFilter")
                .set("columnName", "Publish Status")
                .set("values", new String[]{"PUBLISHED"});
        //2.1、如果要过滤其他条件自行添加。比如过滤 10<=price<=1000
        JSONObject priceFilter = new JSONObject();
        priceFilter.set("type", "rangeFilter")
                .set("columnName", "Price")
                .set("from", "10")
                .set("to", "1000");
        //2.2、把上面所有filter放到filters集合
        JSONArray rowsFilters = new JSONArray();
        rowsFilters.add(statusFilter);
        rowsFilters.add(priceFilter);
        //3、构建body参数，把字段和过滤条件加进来
        JSONObject jsonBody = new JSONObject();
        jsonBody.set("excludeColumns", columns);
        jsonBody.set("rowFilters", rowsFilters);
        log.info("请求参数：{}" + jsonBody);
        String response = request(Method.POST, url, param, JSONUtil.toJsonStr(jsonBody));
        log.info("response：{}", response);
    }