Metodi dell'API Call Data Portability

L'API Data Portability è composta dai seguenti metodi:

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive
  • archiveJobs.cancelPortabilityArchive
  • accessType.check

portabilityArchive.initiate

Chiami il metodo portabilityArchive.initiate per avviare un nuovo job di esportazione dei dati.

Quando avvii un job di esportazione per creare un archivio di dati, devi richiedere il gruppo di risorse appropriato e fornire un token OAuth con gli ambiti richiesti per quel gruppo di risorse. Il token OAuth viene utilizzato per autorizzare la richiesta e per determinare quali dati utente vengono esportati.

Per un elenco di tutti i gruppi di risorse supportati da un determinato servizio, consulta la pagina di riferimento dello schema del servizio in questione.

Ad esempio, se stai esportando i dati delle attività di ricerca, chiami InitiatePortabilityArchive(resources = ["myactivity.search"]). La richiesta deve avere un token OAuth associato con l'ambito OAuth di ricerca:https://www.googleapis.com/auth/dataportability.myactivity.search.

Sebbene sia possibile includere più gruppi di risorse in una singola chiamataInitiatePortabilityArchive, questa operazione non è consigliata. Puoi ottenere un'elaborazione più rapida inviando richieste InitiatePortabilityArchive separate per ogni gruppo di risorse. Tieni presente che quando richiedi più gruppi di risorse, al token OAuth allegato devono essere associati tutti gli ambiti appropriati.

Ad esempio, anziché chiamare InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"]) per creare un archivio di dati sia per la ricerca sia per l'attività su YouTube, effettua queste chiamate separate: InitiatePortabilityArchive(resources = ["myactivity.search"]) e InitiatePortabilityArchive(resources = ["myactivity.youtube"]).

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

archiveJobs.getPortabilityArchiveState

Il metodo archiveJobs.getPortabilityArchiveState viene chiamato per recuperare lo stato corrente del job di esportazione dell'archivio di dati. Quando chiami getPortabilityArchiveState, fornisci job_id: GetPortabilityArchiveState(job_id). Devi anche fornire un token OAuth con ambiti corrispondenti ai gruppi di risorse utilizzati nella richiesta initiate.

Se lo stato è COMPLETE, vengono restituiti URL di Cloud Storage firmati che puoi utilizzare per scaricare i dati. Gli URL firmati scadono dopo sei ore e i dati sono disponibili per 14 giorni.

L'elaborazione di una richiesta di archiviazione può richiedere diversi minuti, diverse ore o addirittura diversi giorni, a seconda del volume di dati. Puoi controllare lo stato dell'archiviazione ogni 5-60 minuti.

resetAuthorization

Il metodo resetAuthorization esegue le seguenti operazioni:

  • Revoca tutti gli ambiti OAuth concessi dall'utente
  • Consente all'applicazione di chiamare InitiatePortabilityArchive per un gruppo di risorse utilizzato in precedenza
  • Rimuove l'accesso agli archivi di dati precedenti

Quando chiami resetAuthorization, devi fornire un token OAuth allegato per l'utente di cui stai reimpostando l'autorizzazione.

archiveJobs.retryPortabilityArchive

Il metodo archiveJobs.retryPortabilityArchive viene chiamato per riprovare i job non riusciti in cui il metodo archiveJobs.getPortabilityArchiveState ha già restituito uno stato di FAILED. Ciò può verificarsi a causa di un errore transitorio sul backend. In questo caso, puoi riprovare a eseguire l'esportazione senza ottenere un nuovo token OAuth dall'utente. Quando chiami retryPortabilityArchive, fornisci job_id insieme a un token OAuth valido. L'endpoint tenta quindi di creare un'esportazione per gli stessi gruppi di risorse richiesti nella richiesta initiatePortabilityArchive iniziale. In caso di esito positivo, questo endpoint restituisce un nuovo job_id che puoi utilizzare nelle chiamate a getPortabilityArchiveState. Per un job non riuscito è possibile riprovare fino a tre volte.

Ad esempio:

  1. Chiami InitiatePortabilityArchive(resources = ["myactivity.search"]) e ricevi job_id: 0.

  2. Dopo aver chiamato GetPortabilityArchiveState(0), ricevi JobSate: FAILED.

  3. Puoi quindi chiamare il numero RetryPortabilityArchive(0) per ricevere job_id: 1 per resources = ["myactivity.search"].

  4. Dopodiché, puoi continuare a effettuare chiamate al numero GetPortabilityArchiveState(1).

archiveJobs.cancelPortabilityArchive

Il metodo archiveJobs.cancelPortabilityArchive viene chiamato per annullare un singolo job senza revocare i token esistenti quando hai accesso continuo ai dati utente. Questa operazione è utile quando un job o una risorsa non sono più necessari e vuoi reimpostare la quota del job. Per poter essere annullato, il job deve essere IN_PROGRESS e deve essere stato creato con accesso basato sul tempo.

Ad esempio, puoi annullare un job in corso basato sul tempo per myactivity.youtube e youtube.public_videos e avviare un nuovo job solo per myactivity.youtube.

accessType.check

Il metodo accessType.check ti consente di verificare se un token OAuth autorizza un accesso basato sul tempo o una tantum prima di avviare un job. Ad esempio, potresti voler esportare l'intera cronologia di un utente se concede l'accesso una tantum o solo l'ultimo giorno se concede l'accesso in base al tempo.

La risposta contiene due campi: elenchi di ID gruppo di risorse per la portabilità dei dati una tantum e basati sul tempo autorizzati dal token OAuth utilizzato nella richiesta. Gli utenti non possono combinare tipi di accesso in una concessione di token, ma non necessariamente dovresti assumere questo comportamento in futuro.