Le nuove funzionalità dell'API Data Portability sono in fase di implementazione e saranno disponibili per tutti entro il 20 febbraio 2025.

Questa pagina è stata tradotta dall'API Cloud Translation.

Applicare filtri temporali alle richieste

In questa guida rapida, ottieni un token OAuth per il tuo account e invii richieste agli endpoint dell'API Data Portability utilizzando i timestamp per filtrare i dati esportati.

Questa guida rapida spiega come utilizzare l'API Data Portability con accesso basato sul tempo e come applicare filtri temporali per le risorse supportate. Per maggiori dettagli sull'accesso ai dati utente in base al tempo, consulta Utilizzare l'accesso in base al tempo.

Cosa imparerai

In questa guida rapida imparerai a:

Invia richieste autenticate ricorrenti all'endpoint InitiatePortabilityArchive per esportare solo i nuovi dati dall'ultima esportazione.
Invia una richiesta autenticata all'endpoint InitiatePortabilityArchive per esportare solo i dati degli ultimi 6 mesi.
Invia una richiesta autenticata all'endpoint InitiatePortabilityArchive per esportare solo i dati di un periodo di tempo specifico.

Prerequisiti

Per eseguire questa guida rapida, devi:

Verifica che l'API Data Portability sia disponibile per gli utenti nella tua località. Per un elenco di paesi e regioni supportati, consulta le Domande frequenti nella pagina "Condividere una copia dei dati con terze parti".
Completa i passaggi di configurazione per l'API Data Portability.
Segui i passaggi per configurare OAuth per le app web JavaScript. In produzione, normalmente si utilizza un flusso diverso, ad esempio il flusso OAuth per le applicazioni server web. Per semplicità, questa guida rapida utilizza il flusso dell'app web JavaScript.
- Quando crei le credenziali di autorizzazione, annota l'ID client OAuth 2.0 e l'URI di reindirizzamento autorizzato (ad esempio https://google.com). Ti serviranno in seguito nella procedura guidata iniziale.
- Quando configuri gli ambiti per l'API Data Portability, tieni presente che questo Quickstart utilizza il myactivity.search gruppo di risorse: https://www.googleapis.com/auth/dataportability.myactivity.search.
- Quando scegli il periodo di tempo per cui vuoi consentire l'accesso, devi selezionare 30 giorni per testare il filtro dei tempi con l'accesso in base al tempo. I filtri orari funzionano anche con l'accesso una tantum.
Ottieni un token OAuth.
Ottenere l'accesso a un account di proprietà o controllato dalla tua organizzazione. I dati delle attività di ricerca di questo account vengono esportati in questa guida introduttiva.

Ottenere un token OAuth

Per questa guida rapida, invii una richiesta di autorizzazione per ottenere un token OAuth utilizzando un URL. Questa procedura utilizza il flusso per le app web JavaScript. Questo flusso non restituisce un token di aggiornamento.

Per un'app di produzione, in genere viene utilizzato un flusso OAuth per ottenere un token di aggiornamento che può essere utilizzato per generare token di accesso su richiesta. Un esempio di questo potrebbe essere il flusso per le app web lato server.

Per ottenere un token OAuth:

Componi un URL come il seguente.
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=token&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value
```
Nell'URL:
- client_id è il tuo ID client OAuth.
- redirect_uri è l'URI di reindirizzamento autorizzato, ad esempio https://google.com.
Tieni presente che l'ambito utilizzato nell'URL per questa guida rapida è l'ambito attività di ricerca. Puoi utilizzare qualsiasi ambito che supporti i filtri di tempo.

Avviso: non combinare gli ambiti dell'API di portabilità dei dati con altri tipi di ambiti, non utilizzare troppi ambiti contemporaneamente o non includere gli ambiti concessi in precedenza, in quanto ciò genera errori. Per maggiori dettagli, vedi Limitazioni dell'ambito.
Incolla l'URL nella barra degli indirizzi del browser e segui i passaggi indicati nel flusso OAuth. Questo flusso richiede di accedere all'account di proprietà o controllato dalla tua organizzazione che stai utilizzando per questa guida rapida.

Si tratta dell'account che fornisce il consenso agli ambiti OAuth. La schermata del consenso dovrebbe avere il seguente aspetto (il testo visualizzato nella schermata potrebbe essere diverso da quello riportato in questa immagine):
Scegli gli ambiti a cui concedere l'accesso e la durata per la condivisione dell'accesso ai dati dell'account (una volta, 30 giorni o 180 giorni). Per questa guida rapida, scegli 30 giorni. I filtri temporali funzionano anche con l'accesso una tantum.
Dopo aver concesso il consenso e stabilito la durata dell'accesso, dovresti essere reindirizzato all'URI di reindirizzamento https://google.com. L'URL generato nella barra degli indirizzi include il token di accesso OAuth.

Ad esempio, se l'account utente concede l'accesso OAuth all'ambitodataportability.myactivity.search, l'URL generato è simile al seguente:
```
https://google.com/#state=developer-specified-value&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
Nell'URL, your_OAuth_token è una stringa che rappresenta il token.

Importante: il token di accesso OAuth scade tra un'ora. Se devi generare un nuovo token, segui i passaggi precedenti.
Per convalidare il token OAuth, incolla questo URL nel browser:
```
https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token
```
La risposta dovrebbe essere simile alla seguente:
```
{
  "azp": <your_azp_value>,
  "aud": <your_aud_value>,
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "exp": "1694210968",
  "expires_in": "3334",
  "access_type": "online"
}
```
Per effettuare richieste non sono necessari i campi azp o aud. Il campo azp rappresenta il client_id del presentatore autorizzato e il campo aud identifica il pubblico a cui è destinato questo token, che sarà uguale a uno degli ID client della tua applicazione.

Nota: puoi anche verificare il token inviando una richiesta HTTP GET.
Recupera il token OAuth e la chiave API. Sono necessari per effettuare chiamate all'API Data Portability.

Invia richieste agli endpoint

In questa guida rapida utilizzi i comandi curl per chiamare gli endpoint dell'API Data Portability con i timestamp per filtrare i dati esportati.Questi comandi richiedono il token OAuth e la chiave API raccolti in precedenza.

Dati dell'ultima esportazione

Puoi utilizzare i filtri di tempo con l'accesso in base al tempo per esportare i nuovi dati dall'ultima esportazione. Ad esempio, considera l'ambito https://www.googleapis.com/auth/dataportability.myactivity.search.

Innanzitutto, invia una richiesta autenticata all'endpoint InitiatePortabilityArchive. Questa richiesta avvia un job di archiviazione per il corpus di dati completo.

Esegui il seguente comando curl:
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Nel comando:
- your_OAuth_token è il tuo token OAuth.
Avviso: il parametro resources deve contenere solo gli ambiti OAuth a cui è stato concesso l'accesso e che supportano i filtri orari. In questo esempio, è stato concesso solo myactivity.search. Se includi gruppi di risorse aggiuntivi o gruppi di risorse non supportati, viene restituito un errore. Per maggiori dettagli, consulta Limitazioni dell'ambito.

La richiesta InitiatePortabilityArchive restituisce un archiveJobId e accessType. L'ID job viene utilizzato per recuperare lo stato dell'archivio dei dati e il tipo di accesso determina se ti è stato concesso l'accesso ai dati una sola volta o in base al tempo. Per l'accesso basato sul tempo, vedrai:
```
{
  "archiveJobId": "<your_job_id_1>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Se non fornisci un token OAuth valido, viene restituito il seguente messaggio di errore:
```
Request had invalid authentication credentials. Expected OAuth 2.0 access
token, login cookie or other valid authentication credential. See
https://developers.google.com/identity/sign-in/web/devconsole-project.
```
Successivamente, invia una richiesta autenticata all'endpoint GetPortabilityArchiveState per recuperare lo stato del job di archiviazione.

Esegui il seguente comando curl:
```
curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/your_job_id_1/portabilityArchiveState
```
Nel comando:
- your_OAuth_token è il tuo token OAuth.
- your_job_id_1 è l'ID job restituito dalla richiesta InitiatePortabilityArchive.
La risposta si basa sullo stato del job. Se il job non è completato, la risposta fornisce lo stato corrente. Devi inviare richieste a questo endpoint periodicamente fino al completamento del job.
```
{
  "state": "IN_PROGRESS"
}
```
Se il job è completato, la risposta contiene lo stato e uno o più URL firmati utilizzati per scaricare l'archivio di dati. Esiste anche un export_time campo che rappresenta il timestamp della prima chiamata a InitiatePortabilityArchive.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}
```
Incolla l'URL firmato nel browser per scaricare l'archivio dei dati. Devi esaminare i contenuti dell'archivio per assicurarti che contengano i dati sulle attività di ricerca previsti.

Nota: il tempo necessario per completare il job di archiviazione dipende dalle dimensioni dell'archivio. La durata massima è di sette giorni.

Se nella risposta ricevi lo stato FAILED, puoi riprovare a eseguire l'esportazione utilizzando il metodo RetryPortabilityArchive.
Attendi almeno 24 ore, quindi invia un'altra richiesta a InitiatePortabilityArchive utilizzando lo stesso comando del passaggio 1, ma questa volta utilizza export_time come start_time.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": timestamp_of_first_initiate_request}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Nota: puoi modificare start_time in modo che si sovrapponga leggermente a export_time per assicurarti che tutti i dati generati tra una richiesta e l'altra siano inclusi nell'esportazione.

Per l'accesso basato sul tempo, verrà restituito quanto segue:
```
{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Ripeti il passaggio 2 per inviare una richiesta autenticata all'endpoint GetPortabilityArchiveState per recuperare lo stato del job di archiviazione (utilizzando <your_job_id_2>).

Al termine del job, la risposta sarà:

  {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

Verifica che i dati della seconda esportazione contengano solo i nuovi dati generati dopo la prima esportazione.

Dati degli ultimi 6 mesi

Puoi anche utilizzare i filtri di tempo per esportare solo i dati più recenti anziché tutto il corpus.

Supponiamo che la data di oggi sia 2024-10-01 e che tu voglia esportare i dati degli ultimi 6 mesi. Innanzitutto, invia una richiesta autenticata all'endpoint InitiatePortabilityArchive con un valore start_time di "2024-04-01T00:00:00Z".

Esegui il seguente comando curl:

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2024-04-01T00:00:00Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

Per l'accesso basato sul tempo, verrà restituito quanto segue:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Invia una richiesta all'endpoint GetPortabilityArchiveState per recuperare lo stato del job di archiviazione.

Esegui il seguente comando curl:
```
curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/job_id_1/portabilityArchiveState
```
Al termine del job, la risposta sarà:
```
{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}
```
Tieni presente che start_time è il valore start_time specificato nel passaggio 1 e export_time è il timestamp della chiamata a InitiatePortabilityArchive effettuata nel passaggio 1.
Verifica che l'esportazione contenga solo i dati degli ultimi sei mesi.

Dati relativi a un periodo di tempo specifico

Puoi utilizzare i filtri di tempo per esportare i dati da un intervallo di date specifico, ad esempio solo i dati del 2023.

Innanzitutto, invia una richiesta autenticata all'endpoint InitiatePortabilityArchive con un valore start_time di "2023-01-01T00:00:00Z" e un valore end_time di "2023-12-31T23:59:59Z".

Esegui il seguente comando curl:

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

Per l'accesso basato sul tempo, verrà restituito quanto segue:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Invia una richiesta all'endpoint GetPortabilityArchiveState per recuperare lo stato del job di archiviazione.

Esegui il seguente comando curl:

curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/job_id_1/portabilityArchiveState

Al termine del job, la risposta sarà:

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

Tieni presente che start_time è il start_time specificato nel passaggio 1 e export_time è uguale a end_time fornito nel passaggio 1.

Verifica che l'esportazione contenga solo i dati del 2023.

Ambiti supportati

I seguenti ambiti supportano i filtri relativi al tempo:

https://www.googleapis.com/auth/dataportability.myactivity.youtube
https://www.googleapis.com/auth/dataportability.myactivity.maps
https://www.googleapis.com/auth/dataportability.myactivity.search
https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
https://www.googleapis.com/auth/dataportability.myactivity.shopping
https://www.googleapis.com/auth/dataportability.myactivity.play
https://www.googleapis.com/auth/dataportability.chrome.history

Attenzione: le richieste con filtro temporale che combinano ambiti supportati e non supportati generano un errore INVALID_ARGUMENT con il messaggio The requested resources do not support time filters.