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 richiesta autenticata con un token OAuth valido all'endpoint InitiatePortabilityArchive una seconda volta 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 lato server.
    • Quando crei le credenziali di autorizzazione, annota l'ID client OAuth 2.0, il client secret e l'URI di reindirizzamento autorizzato (ad esempio https://google.com). Ti serviranno più avanti nella guida rapida.
    • 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. Questo processo utilizza il flusso per le app web lato server. Questo flusso genera un token di aggiornamento che puoi utilizzare per le esportazioni successive.

Per ottenere un token OAuth:

  1. Componi un URL come il seguente.

    https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=code&
access_type=offline&
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.

  2. 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 introduttiva.

    Si tratta dell'account che fornisce il consenso per gli 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):

    La schermata del consenso in cui l'utente accetta di consentire l'accesso ai dati delle attività di ricerca

  3. 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.

  4. 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 un codice di autorizzazione che scambierai con un token OAuth nel passaggio successivo.

    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&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

  5. Per scambiare un codice di autorizzazione con un token di accesso, chiama l'endpoint del token OAuth con:

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'

    La risposta dovrebbe essere simile alla seguente:

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}

    Nell'URL, your_OAuth_token è una stringa che rappresenta il token.

    Il campo refresh_token_expires_in è in secondi e indica se l'utente ha scelto 30 giorni (2592000 secondi) o 180 giorni (15552000 secondi) di accesso. Se lo stato di pubblicazione della tua app è Test, hai 7 giorni (604800 secondi) di accesso indipendentemente dalla selezione dell'utente.

  6. 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.

  7. 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:

  1. 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.

    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.

  2. 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 relativi all'attività di ricerca previsti.

    Se nella risposta ricevi lo stato FAILED, puoi riprovare a eseguire l'esportazione utilizzando il metodo RetryPortabilityArchive.

  3. 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}"
...

  4. Dopo 24 ore puoi richiedere una nuova esportazione, ma devi prima scambiare il token di aggiornamento con un token di accesso nuovo.

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'

    La risposta dovrebbe essere simile alla seguente:

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}

    Se l'utente rinnova l'accesso, la nuova data e ora di scadenza vengono riportate nel campo refresh_token_expires_in.

    Puoi utilizzare il nuovo token di accesso per ripetere i passaggi InitiatePortabilityArchive e GetPortabilityArchiveState.