Inizia a utilizzare l'API Data Portability

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

Cosa imparerai

In questa guida rapida scoprirai come:

  • Invia una richiesta autenticata all'endpoint InitiatePortabilityArchive fornendo un token OAuth valido. La risposta deve contenere un elemento 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'endpoint InitiatePortabilityArchive utilizzando le stesse credenziali. Viene restituito un errore RESOURCE_EXHAUSTED e lo scopo è sottolineare 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 che hai utilizzato in precedenza. La richiesta dovrebbe non riuscire dopo la reimpostazione 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 dei paesi e delle regioni supportati, consulta le Domande comuni nella pagina "Condividere una copia dei tuoi dati con terze parti".
  • Completa la procedura di configurazione per l'API Data Portability.
  • Segui i passaggi per configurare OAuth per le app web JavaScript. In produzione, utilizzerai solitamente un flusso diverso, come 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, prendi nota del tuo ID client OAuth 2.0 e dell'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 questa guida rapida utilizza il gruppo di risorse myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
  • Procurati un token OAuth.
  • Ottenere l'accesso a un account di proprietà o controllato dalla tua organizzazione. I dati sull'attività di ricerca di questo account vengono esportati in questa guida rapida.

Ottenere un token OAuth

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

Per un'app di produzione, in genere si utilizza un flusso OAuth per ottenere un token di aggiornamento da utilizzare per generare token di accesso on demand. Un esempio potrebbe essere il flusso per le app web lato server.

Per ottenere un token OAuth:

  1. Scrivi un URL come riportato di seguito.

    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&
include_granted_scopes=true&
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 di questa guida rapida è l'ambito dell'attività di ricerca. Puoi anche utilizzare l'ambito delle attività di YouTube o entrambi gli ambiti.

  2. Incolla l'URL nella barra degli indirizzi del browser e segui i passaggi del flusso OAuth. Questo flusso richiede l'accesso all'account di proprietà o controllato dalla tua organizzazione che utilizzi per questa guida rapida.

    Si tratta dell'account che acconsente agli ambiti OAuth. La schermata per il consenso dovrebbe avere il seguente aspetto (il testo sullo schermo può variare rispetto a quello in questa immagine):

    La schermata per il consenso in cui l'utente acconsente ad accedere ai dati dell'attività di ricerca

  3. Dopo aver concesso il consenso, dovresti essere inoltrato 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'ambito dataportability.myactivity.search, l'URL generato sarà simile a questo:

    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.

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

  5. Procurati il token OAuth e la chiave API. Sono necessari per effettuare chiamate all'API Data Portability.

Invia richieste agli endpoint

In questa guida rapida userai i comandi curl per chiamare gli endpoint dell'API Data Portability. Questi comandi richiedono il token OAuth e la chiave API che hai raccolto in precedenza.

Per chiamare l'API Data Portability:

  1. Innanzitutto, invii 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.

    NOTA: 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 gruppi di risorse aggiuntivi, viene restituito un errore.

    La richiesta InitiatePortabilityArchive restituisce un job_id. Questo ID job viene utilizzato per recuperare lo stato dell'archivio dati.

    {
  "archiveJobId": "<your_job_id>"
}

    Se non fornisci un token OAuth valido, viene restituito questo 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 state del job. Se il job non è completo, la risposta fornisce lo stato attuale. Devi inviare periodicamente richieste a questo endpoint fino al completamento del job.

    {
  "state": "IN_PROGRESS"
}

    Se il job è completo, la risposta contiene lo stato e uno o più URL firmati utilizzati per scaricare l'archivio dati.

    {
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}

    Incolla l'URL firmato nel browser per scaricare l'archivio dati. Dovresti esaminare i contenuti dell'archivio per assicurarti che contenga i dati relativi all'attività di ricerca prevista.

  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 dovrebbe indicare che il consenso una tantum per la risorsa myactivity.search è esaurito per questo utente.

    ...
  "error":
    {
      "code": 429,
  "message": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

  4. Invia una richiesta autenticata all'endpoint ResetAuthorization. Questa richiesta revoca tutti gli ambiti OAuth concessi dall'utente e 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. Usa 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 che hai 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"
  }