Inizia a utilizzare l'API Data Portability

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

Questa guida rapida spiega come utilizzare l'API Data Portability per l'accesso una tantum ai dati degli utenti. Per l'accesso continuo ai dati utente, vedi Utilizzare l'accesso basato sul tempo. Per scoprire come applicare i filtri di tempo alla richiesta, consulta Applicare i filtri di tempo.

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.
  • (Facoltativo) Invia una seconda volta una richiesta autenticata con un token OAuth valido all'endpointInitiatePortabilityArchive utilizzando le stesse credenziali. Viene restituito un errore RESOURCE_EXHAUSTED e lo scopo è mettere in evidenza l'importanza dell'endpoint ResetAuthorization.
  • Invia una richiesta autenticata all'endpoint ResetAuthorization. Questa richiesta revoca tutti gli ambiti OAuth concessi dall'utente.
  • (Facoltativo) Invia una richiesta all'endpoint InitiatePortabilityArchive utilizzando lo stesso token OAuth utilizzato in precedenza. La richiesta dovrebbe non andare a buon fine dopo il ripristino dell'autorizzazione.

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, questa procedura guidata introduttiva utilizza 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:

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

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

    Si tratta dell'account che fornisce il consenso agli ambiti OAuth. La schermata per il consenso dovrebbe avere il seguente aspetto (il testo visualizzato nella schermata potrebbe essere diverso da quello riportato nell'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 Solo una volta.

  4. Dopo aver concesso il consenso e scelto 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.

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

  6. 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. Ai fini di questa guida rapida, dovresti avere un accesso una tantum.

    {
  'archiveJobId': '<your_job_id>'
  'accessType': 'ACCESS_TYPE_ONE_TIME'
}

    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 sulle attività di ricerca previsti.

  3. (Facoltativo) 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 deve indicare che il consenso una tantum per la risorsamyactivity.search è esaurito per questo utente.

    ...
"error": {
    "code": 429,
    "message": "Requested resources have already been exported. Please call ResetAuthorization and re-obtain consent before trying again.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "{previous_job_ids}"
    "access_type": "ACCESS_TYPE_ONE_TIME"
...

  4. Invia una richiesta autenticata all'endpoint ResetAuthorization. Questa richiesta revoca tutti gli ambiti OAuth concessi dall'utente e ti consente di chiamare InitiatePortabilityArchive per un gruppo di risorse che hai già utilizzato.

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset

    Nel comando:

    • your_OAuth_token è il tuo token OAuth.

    Questo comando restituisce una risposta vuota.

  5. (Facoltativo) Dopo aver reimpostato l'autorizzazione, invia un'altra richiesta all'endpoint InitiatePortabilityArchive. Utilizza lo stesso comando curl usato in precedenza.

    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 restituire un errore perché il token OAuth fornito è stato revocato.

    ...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }