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.

Usa l'accesso basato sul tempo

In questa guida rapida, ottieni un token OAuth per il tuo account e invii richieste ricorrenti agli endpoint dell'API Data Portability.

Questa guida rapida illustra come utilizzare l'API Data Portability per l'accesso in base al tempo ai dati degli utenti. Per l'accesso una tantum ai dati utente, consulta Iniziare a utilizzare l'API Data Portability. Per scoprire come applicare i filtri temporali alla tua richiesta, consulta Applicare i filtri temporali.

Cosa imparerai

In questa guida rapida imparerai a:

Invia una richiesta autenticata all'endpoint InitiatePortabilityArchive fornendo un token OAuth valido. La risposta deve contenere un valore job_id valido.
Invia una richiesta autenticata all'endpoint GetPortabilityArchiveState. La risposta deve contenere uno stato del job valido e, al termine del job, un URL firmato.
Invia una seconda volta una richiesta autenticata con un token OAuth valido all'endpoint InitiatePortabilityArchive utilizzando le stesse credenziali. Viene restituito un errore FAILED_PRECONDITION quando la richiesta viene effettuata entro 24 ore dalla richiesta iniziale.

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 l'accesso basato sul tempo.
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 anche utilizzare l'ambito Attività su YouTube o entrambi.

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.
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 utilizzerai i comandi curl per chiamare gli endpoint dell'API Data Portability. Questi comandi richiedono il token OAuth e la chiave API raccolti in precedenza.

Per chiamare l'API Data Portability:

Innanzitutto, invia una richiesta autenticata all'endpoint InitiatePortabilityArchive. Questa richiesta avvia un job di archiviazione.

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. In questo esempio, è stato concesso solo myactivity.search. Se includi altri gruppi di risorse, viene restituito un errore. Per maggiori dettagli, consulta Restrizioni di ambito.

La richiesta InitiatePortabilityArchive restituisce un job_id 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>"
  "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/portabilityArchiveState
```
Nel comando:
- your_OAuth_token è il tuo token OAuth.
- your_job_id è 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.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
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.

Ripeti il comando precedente per inviare una richiesta autenticata all'endpoint InitiatePortabilityArchive.

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.

La risposta dovrebbe indicare che hai già esportato la risorsa myactivity.search e un timestamp per quando puoi riprovare.

...
  "error": {
    "code": 429,
    "message": "Requested resources have already been exported. You can initiate another export after #{timestamp_after_24hrs}.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "#{previous_job_ids}"
    "access_type": "ACCESS_TYPE_TIME_BASED"
    "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
...