Eseguire la migrazione dalla versione 1.1 alla v2 dell'API di Bid Manager

A marzo 2022 abbiamo rilasciato la versione 2 dell'API Bid Manager. Considerando il rilascio di questa nuova versione, prevediamo di annunciare a breve una data di ritiro per la versione 1.1. Ti consigliamo di iniziare la migrazione dalla versione 1.1 alla versione 2 il prima possibile.

Esegui la migrazione dell'applicazione

La migrazione dalla versione 1.1 alla versione 2 richiede l'aggiornamento degli URL degli endpoint per chiamare la versione 2 e l'aggiornamento dell'applicazione per tenere conto delle modifiche che causano interruzioni.

Aggiorna le chiamate API dalla versione 1.1 alla versione 2

Per utilizzare la versione 2 anziché la versione 1.1, devi aggiornare le richieste in modo che utilizzino i nuovi endpoint della versione 2.

Identifica i metodi equivalenti

Per aggiornare le chiamate API in modo che utilizzino la versione 2 anziché la versione 1.1, devi prima identificare i metodi equivalenti della versione 1.1 nella versione 2.

I seguenti nomi di tutti i servizi e i metodi sono stati leggermente modificati tra la versione 1.1 e la versione 2:

• I servizi Queries e Reports nella versione 1.1 sono noti come queries e queries.reports nella versione 2.
• I metodi sono stati rinominati come segue nella versione 2:

  Nome del metodo della versione 1.1	Metodo equivalente della versione 2
  Queries.createquery	queries.create
  Queries.deletequery	queries.delete
  Queries.getquery	queries.get
  Queries.listqueries	queries.list
  Queries.runquery	queries.run
  Reports.listreports	queries.reports.list

Esegui l'aggiornamento ai nuovi endpoint

Una volta identificati i metodi equivalenti, devi aggiornare le richieste. Ad esempio, per chiamare il queries.getquery metodo con la versione 1.1, utilizzeresti il seguente URL:

https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId

Per chiamare il metodo equivalente nella versione 2, noto come queries.get, aggiorna l' URL come segue:

GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId

Se utilizzi una libreria client per effettuare richieste all'API, utilizza la versione più recente della libreria client e aggiorna la configurazione in modo che utilizzi la versione 2.

Apporta le modifiche desiderate

Nella versione 2 sono state introdotte diverse modifiche che causano interruzioni. Esamina le seguenti istruzioni e apporta le modifiche necessarie relative all'utilizzo esistente dell'API Bid Manager.

Aggiorna le chiamate al servizio queries

• I seguenti campi nella risorsa Query originariamente rappresentati da oggetti nidificati generali sono stati modificati in modo da utilizzare i seguenti tipi di oggetti:

  Campo della versione 1.1	Tipo di oggetto equivalente della versione 2
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Rimosso
  params.options.pathQueryOptions.channelGrouping	Rimosso
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Rimosso
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Rimosso
  schedule	QuerySchedule

• I seguenti campi nella risorsa Query originariamente rappresentati da oggetti elenco generali sono stati modificati in modo da essere elenchi dei seguenti nuovi tipi di oggetti:

  Campo elenco della versione 1.1	Tipo di oggetto della versione 2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Rimosso
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Rimosso
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Rimosso
  params.options.pathQueryOptions.pathFilters[]	Rimosso
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Rimosso

• I seguenti campi nella risorsa Query, originariamente rappresentati da stringhe, sono rappresentati da tipi di enumerazione nella versione 2 e includono le seguenti modifiche:
  • L'equivalente della versione 2 di metadata.dataRange ora utilizza l'enumerazione Range. Durante la conversione a questa enumerazione, il valore PREVIOUS_HALF_MONTH è stato rimosso e il valore TYPE_NOT_SUPPORTED è stato modificato in RANGE_UNSPECIFIED.
  • metadata.format ora utilizza l'enumerazione Format. Durante la conversione a questa enumerazione, il valore EXCEL_CSV è stato rimosso e il valore FORMAT_UNSPECIFIED è stato aggiunto.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match e params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match ora utilizzano l'enumerazione Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition ora utilizza l'enumerazione PathMatchPosition. Durante la conversione a questa enumerazione, il valore PATH_MATCH_POSITION_UNSPECIFIED è stato aggiunto.
  • schedule.frequency ora utilizza l'enumerazione Frequency. Durante la conversione a questa enumerazione, il valore FREQUENCY_UNSPECIFIED è stato aggiunto.
  • params.type ora utilizza l'enumerazione ReportType. Durante la conversione a questa enumerazione, sono state apportate le seguenti modifiche:
  • I seguenti valori sono stati ritirati:
    • TYPE_ACTIVE_GRP
    • TYPE_AUDIENCE_PERFORMANCE
    • TYPE_CLIENT_SAFE
    • TYPE_COMSCORE_VCE
    • TYPE_CROSS_FEE
    • TYPE_CROSS_PARTNER
    • TYPE_CROSS_PARTNER_THIRD_PARTY_DATA_PROVIDER
    • TYPE_ESTIMATED_CONVERSION
    • TYPE_FEE
    • TYPE_KEYWORD
    • TYPE_LINEAR_TV_SEARCH_LIFT
    • TYPE_NIELSEN_AUDIENCE_PROFILE
    • TYPE_NIELSEN_DAILY_REACH_BUILD
    • TYPE_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PAGE_CATEGORY
    • TYPE_PETRA_NIELSEN_DAILY_REACH_BUILD
    • TYPE_PETRA_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PIXEL_LOAD
    • TYPE_THIRD_PARTY_DATA_PROVIDER
    • TYPE_TRUEVIEW_IAR
    • TYPE_VERIFICATION
    • TYPE_YOUTUBE_VERTICAL
  • Tutti i valori rimanenti sono stati aggiornati per riflettere meglio i valori equivalenti nell'interfaccia utente:

    Valori della versione 1.1	Valore ReportType equivalente
    TYPE_NOT_SUPPORTED	REPORT_TYPE_UNSPECIFIED
    TYPE_GENERAL	STANDARD
    TYPE_INVENTORY_AVAILABILITY	INVENTORY_AVAILABILITY
    TYPE_AUDIENCE_COMPOSITION	AUDIENCE_COMPOSITION
    TYPE_ORDER_ID	FLOODLIGHT
    TYPE_TRUEVIEW	YOUTUBE
    TYPE_NIELSEN_SITE	GRP
    TYPE_PETRA_NIELSEN_AUDIENCE_PROFILE	YOUTUBE_PROGRAMMATIC_GUARANTEED
    TYPE_REACH_AND_FREQUENCY	REACH
    TYPE_REACH_AUDIENCE	UNIQUE_REACH_AUDIENCE
    TYPE_PATH	FULL_PATH
    TYPE_PATH_ATTRIBUTION	PATH_ATTRIBUTION

• I campi metadata.dataRange, reportDataStartTimeMs e reportDataEndTimeMs sono stati sostituiti dai campi range, customStartDate e customEndDate. I nuovi campi data utilizzano Date oggetti anziché millisecondi dall'epoca Unix. Questi campi di sostituzione sono stati spostati nell'oggetto DataRange assegnato al campo dataRange nell'oggetto QueryMetadata.
• I campi schedule.startTimeMs e schedule.endTimeMs sono stati sostituiti dai campi startDate e endDate nell' oggetto QuerySchedule. I nuovi campi data utilizzano Date oggetti anziché millisecondi dall'epoca Unix.
• I campi metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport e metadata.latestReportRunTimeMs sono stati rimossi. Le informazioni relative ai report generati più di recente di una query devono essere recuperate utilizzando il metodo queries.reports.list con il orderBy parametro di query "key.reportId desc" per garantire che la richiesta elenchi prima i report più recenti.
• I campi kind, timezoneCode, metadata.locale, params.includeInviteData e schedule.nextRunMinuteOfDay sono stati rimossi.
• queries.create non esegue più automaticamente le query dopo la creazione e il parametro di query asynchronous è stato rimosso. Chiama queries.run dopo queries.create per generare report per nuove query.
• Il metodo queries.run è stato aggiornato nei seguenti modi:
  • Il parametro di query asynchronous è stato sostituito dal parametro di query synchronous. Il nuovo parametro di query funziona con la logica inversa e viene considerato falso se non specificato. Di conseguenza, queries.run genera report in modo asincrono per impostazione predefinita nella versione 2, a differenza della versione 1.1, in cui è sincrono.
  • Il corpo della richiesta è stato aggiornato per rimuovere il timezoneCode campo e sostituire dataRange, reportDataStartTimeMs, reportDataEndTimeMs campi con un DataRange oggetto assegnato al dataRange campo.
  • Il metodo restituisce l'oggetto Report risultante anziché un corpo della risposta vuoto.
• Il campo kind nel corpo della risposta queries.list è stato rimosso.

Aggiorna le chiamate al servizio reports

• I seguenti campi nella risorsa Report originariamente rappresentati da oggetti nidificati generali sono stati modificati in modo da utilizzare i seguenti tipi di oggetti:

  Campo della versione 1.1	Tipo di oggetto equivalente della versione 2
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Rimosso
  params.options.pathQueryOptions.channelGrouping	Rimosso
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Rimosso
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Rimosso

• I seguenti campi nella risorsa Report originariamente rappresentati da oggetti elenco generali sono stati modificati in modo da essere elenchi dei seguenti nuovi tipi di oggetti:

  Campo elenco della versione 1.1	Tipo di oggetto della versione 2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Rimosso
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Rimosso
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Rimosso
  params.options.pathQueryOptions.pathFilters[]	Rimosso
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Rimosso

• I seguenti campi nella risorsa Report originariamente rappresentati da stringhe sono stati modificati in modo che i campi equivalenti nella versione 2 siano rappresentati da nuovi tipi di enumerazione e includano modifiche ai valori accettabili:
  • metadata.status.format ora utilizza l'enumerazione Format. Durante la conversione a questa enumerazione, il valore EXCEL_CSV è stato rimosso e il valore FORMAT_UNSPECIFIED è stato aggiunto.
  • metadata.status.state ora utilizza l'enumerazione State. Durante la conversione a questa enumerazione, i valori QUEUED e STATE_UNSPECIFIED sono stati aggiunti.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match e params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match ora utilizzano l'enumerazione Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition ora utilizza l'enumerazione PathMatchPosition. Durante la conversione a questa enumerazione, il valore PATH_MATCH_POSITION_UNSPECIFIED è stato aggiunto.
  • params.type ora utilizza l'enumerazione ReportType. Durante la conversione a questa enumerazione, sono state apportate numerose modifiche, elencate in dettaglio nella sezione precedente relativa all'aggiornamento delle chiamate al servizio queries.
• I campi metadata.reportDataStartTimeMs e metadata.reportDataEndTimeMs sono stati sostituiti dai campi reportDataStartDate e reportDataEndDate nell' ReportMetadata oggetto. I nuovi campi utilizzano Date oggetti anziché millisecondi dall'epoca Unix.
• metadata.status.finishTimeMs è stato sostituito dal campo finishTime nell'oggetto ReportStatus. Questo nuovo campo di ora rappresenta la data e l'ora come timestamp in formato "Zulu" UTC RFC3339 anziché in millisecondi dall'epoca Unix.
• metadata.status.failure e params.includeInviteData campi sono stati rimossi.
• Il campo kind nel corpo della risposta reports.list è stato rimosso.

Aggiorna la logica di gestione degli errori

I messaggi di errore nell'API sono stati aggiornati nella versione 2. Questi nuovi messaggi di errore sono più specifici e, in alcuni casi, forniscono informazioni sui valori nella richiesta API che causano la restituzione dell'errore. Se la logica di gestione degli errori esistente si basa su un testo specifico del messaggio di errore, generalizza la gestione degli errori prima di eseguire la migrazione alla versione 2.