Upgrade API version to V3

[nguyentoanit]

No description provided.

[nguyentoanit]

@moltar: Could i migrate API to V3 after finish all issue?
At the moment, our lib still requests to API V2.
If upgrade, we need to update operations and their tests.

[moltar]

Yeah, sure!

[nguyentoanit]

@moltar : I have tried to upgrade to V3 with url paths (sb, v3/sb, v3/hsa) But always return Resource Not Found Error.
It seems to be not available on Sandbox API.
Do we need create an issue to Amazon?

Or i skip this issue and start working on another project?
And resolve them when they're available.

[moltar]

@nguyentoanit can you please share the docs where you've seen the v2 -> v3 upgrade being mentioned? Thanks.

[nguyentoanit]

@moltar : I found them on Release Note. You can find "Version 3 of the Amazon Advertising API is now available" on Release Note.

I tried sb url path on reference documentation
It returned a Resource Not Found Error. The docs don't mention about v3/sb, v3/hsa but i still try them (because i think the docs may be not updated yet).

[moltar]

I think the v3 is limited to the following:

For Sponsored Brands specific elements, the new version of the API introduces the ability to create a Sponsored Brand campaign via the API, upload and retrieve creative assets, retrieve the brand associated with a specific profile, and access creative and landing page information in the Sponsored Brands campaign object.

[moltar]

So maybe try:

• create a Sponsored Brand campaign
• upload and retrieve creative assets
• retrieve the brand associated with a specific profile

operations

[nguyentoanit]

• create a Sponsored Brand campaign
• retrieve the brand associated with a specific profile

I have tried but still get an error.

upload and retrieve creative assets

I couldn't determine which operation do it.

[nguyentoanit]

@moltar : I still have left issue and also reported the result about API V3 on test API above. 👍

[moltar]

Hm, which country are you testing this on?

I think some of these new API endpoints only work in US for now.

[nguyentoanit]

@moltar : I'm testing on Sandbox API. I don't have a Production token to test.

[moltar]

Right, but you can still target different countries based by supplying that to an http constructor.

How about this. Create a failing test PR and I’ll take a look.

[nguyentoanit]

@moltar: I created a failing test. Please help me take a look it. Thanks.

[moltar]

From Amazon support:

Sandbox environment for Sponsored Brands campaigns is not currently available for testing. This is in our backlog but not prioritized at the moment. It is recommended to test the functionality on existing campaigns such as list operations.

So, I think it is not possible to use sandbox for testing.

In which case, we should just ignore tests for now, and just assume that it works 🤷‍♂️

[MIT120]

Hi, any Idea if the sdk will migrate to v3 any time soon?
The support for v2 is till march for and June this year.
Many thanks for your time!

[moltar]

@MIT120 There are no plans yet. We have to see how the OpenAPI specs shape up over time. We might use the same approach as we use on the SP API SDK to auto-generate the models from the spec. This would be a one-time, breaking change.

[NiciusB]

The v2 endpoints for sponsored product reports are being deprecated next week.

If someone needs a solution for now, I've cobbled together a custom operation you can use for V3's Reports:

import { Operation } from '@scaleleap/amazon-advertising-api-sdk'
import assert from 'node:assert'

export default class ReportsV3Operation extends Operation {
  async getReport(reportId: string): Promise<AsyncReport> {
    return await this.client.get(`reporting/reports/${reportId}`)
  }

  async deleteReport(reportId: string): Promise<DeleteAsyncReportResponse> {
    return await this.client.delete(`reporting/reports/${reportId}`)
  }

  async createReport(body: CreateAsyncReportRequest): Promise<AsyncReport> {
    return await this.client.post(`reporting/reports`, body)
  }

  async downloadReportDocument(report: AsyncReport) {
    /*
    You'll need to implement this by yourself. I've done something like this:
    
    import { ungzip } from 'node-gzip'
    const fetchRes = await fetch(url)
    const resultText = await ungzip(await fetchRes.arrayBuffer()).then((x) =>
      x.toString('utf-8')
    )
    return JSON.parse(resultText)
   */
  }
}

/**
 * Types created with openapi-to-ts, based on https://dtrnk0o2zy01c.cloudfront.net/openapi/en-us/dest/OfflineReport_prod_3p.json
 */

export type CreateAsyncReportRequest = {
  endDate: string
  configuration: AsyncReportConfiguration
  name?: string
  startDate: string
}

export type AsyncReport = {
  reportId: string
  endDate: string
  configuration: AsyncReportConfiguration
  urlExpiresAt?: string | null
  url?: string | null
  createdAt: string
  fileSize?: number | null
  failureReason?: string | null
  name?: string | null
  generatedAt?: string | null
  startDate: string
  status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED'
  updatedAt: string
}

export type AsyncReportFilter = {
  field?: string
  values?: string[]
}

/**
 * The Error Response.
 */
export type AsyncReportingError = {
  code?: string
  details?: string
}

export type DeleteAsyncReportResponse = {
  code?: string
  reportId?: string
  details?: string
}

export type AsyncReportConfiguration = {
  adProduct: AsyncReportAdProduct
  columns: string[]
  reportTypeId: string
  format: 'GZIP_JSON'
  groupBy: string[]
  filters?: AsyncReportFilter[] | null
  timeUnit: 'SUMMARY' | 'DAILY'
}

/**
 * The advertising product such as SPONSORED_PRODUCTS or SPONSORED_BRANDS.
 */
export type AsyncReportAdProduct = 'SPONSORED_PRODUCTS' | 'SPONSORED_BRANDS'

[moltar]

@NiciusB Maybe PR it? ;)

[NiciusB]

I started adapting it, but it still needs work improving types and adding operations for all specific report types: https://github.com/ScaleLeap/amazon-advertising-api-sdk/compare/master...NiciusB:amazon-advertising-api-sdk:master?expand=1

If I end up finishing it I'll open a PR

[wuqingabc]

@NiciusB Do you have it done? Need your help on this my friend :-)

[hung-datadive]

Do we have any update on V3? Amazon will remove a lot of V2 SP APIs in 6 weeks.
https://advertising.amazon.com/API/docs/en-us/info/deprecations

[moltar]

Currently, we do not have plans to implement additional functionality for v3.

[Javadebi]

Currently, we do not have plans to implement additional functionality for v3.

V2 is deprecating right now, Do you guys have plans on upgrading to v3?