Nowe funkcje interfejsu Data Portability API są wprowadzane i będą dostępne dla wszystkich do 20 lutego 2025 r.

Ta strona została przetłumaczona przez Cloud Translation API.

Stosowanie filtrów czasowych do żądań

W tym krótkim samouczku uzyskasz token OAuth dla swojego konta i wyślesz żądania do punktów końcowych interfejsu Data Portability API, używając sygnatur czasowych do filtrowania eksportowanych danych.

W tym krótkim przewodniku dowiesz się, jak korzystać z interfejsu Data Portability API z dostępem opartym na czasie i jak stosować filtry czasowe w przypadku obsługiwanych zasobów. Więcej informacji o dostępie do danych użytkownika na podstawie czasu znajdziesz w artykule Korzystanie z dostępu na podstawie czasu.

Czego się nauczysz

Z tego krótkiego wprowadzenia dowiesz się, jak:

Aby eksportować tylko nowe dane od czasu ostatniego eksportu, wysyłaj powtarzające się uwierzytelnione żądania do punktu końcowego InitiatePortabilityArchive.
Aby wyeksportować tylko dane z ostatnich 6 miesięcy, wyślij uwierzytelnione żądanie do punktu końcowego InitiatePortabilityArchive.
Aby wyeksportować dane tylko z określonego przedziału czasu, wyślij uwierzytelnione żądanie do punktu końcowego InitiatePortabilityArchive.

Wymagania wstępne

Aby uruchomić to krótkie wprowadzenie:

Sprawdź, czy interfejs Data Portability API jest dostępny dla użytkowników w Twojej lokalizacji. Listę obsługiwanych krajów i regionów znajdziesz w sekcji Najczęstsze pytania na stronie „Udostępnianie kopii danych innej firmie”.
Wykonaj czynności konfiguracyjne interfejsu Data Portability API.
Wykonaj czynności opisane w sekcji Konfigurowanie OAuth w przypadku aplikacji internetowych w języku JavaScript. W wersji produkcyjnej zwykle używasz innego sposobu, na przykład ścieżki OAuth w aplikacjach serwera WWW. W tym krótkim wprowadzeniu używamy ścieżki aplikacji internetowej w języku JavaScript ze względu na jej prostotę.
- Podczas tworzenia danych uwierzytelniających zanotuj identyfikator klienta OAuth 2.0 i autoryzowany identyfikator URI przekierowania (np. https://google.com). Będą one potrzebne w dalszej części samouczka.
- Podczas konfigurowania zakresów interfejsu Data Portability API pamiętaj, że ten samouczek używa myactivity.search grupy zasobów: https://www.googleapis.com/auth/dataportability.myactivity.search.
- Aby przetestować filtrowanie według czasu, wybierz 30 dni jako czas dostępu. (Filtry czasowe działają też w przypadku jednorazowego dostępu).
Uzyskaj token OAuth.
uzyskać dostęp do konta należącego do organizacji lub kontrolowanego przez nią. W tym samouczku dane o aktywności związanej z wyszukiwaniem na tym koncie są eksportowane.

Uzyskiwanie tokena OAuth

W tym krótkim wprowadzeniu wyślesz żądanie autoryzacji, aby uzyskać token OAuth, używając adresu URL. Ten proces wykorzystuje proces dotyczący aplikacji internetowych w JavaScript. Ten proces nie zwraca tokena odświeżania.

W przypadku aplikacji produkcyjnej zwykle używa się procesu OAuth do uzyskiwania tokena odświeżania, który można wykorzystać do generowania tokenów dostępu na żądanie. Przykładem tego jest przepływ danych w aplikacji internetowych po stronie serwera.

Aby uzyskać token OAuth:

Utwórz adres URL podobny do tego:
```
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
```
W adresie URL:
- client_id to identyfikator klienta OAuth.
- redirect_uri to autoryzowany identyfikator URI przekierowania, np. https://google.com.
Zwróć uwagę, że zakres użyty w adresie URL tego krótkiego wprowadzenia to zakres aktywności wyszukiwania. Możesz używać dowolnych zakresów, które obsługują filtry czasowe.

Ostrzeżenie: nie mieszaj zakresów interfejsu Data Portability API z innymi zakresami, nie używaj zbyt wielu zakresów naraz ani nie uwzględniaj wcześniej przyznanych zakresów, ponieważ może to spowodować błędy. Szczegółowe informacje znajdziesz w ograniczeniach zakresu.
Wklej adres URL na pasku adresu przeglądarki i postępuj zgodnie z instrukcjami procesu OAuth. W tym procesie musisz zalogować się na konto należące do Twojej organizacji lub przez nią kontrolowane, którego używasz w tym samouczku.

To jest konto, które wyraża zgodę na zakresy OAuth. Ekran zgody powinien wyglądać tak (tekst na Twoim ekranie może się różnić od tekstu na tym obrazie):
Wybierz zakresy, do których chcesz przyznać dostęp, oraz czas udostępniania dostępu do danych na koncie (raz, 30 dni lub 180 dni). Na potrzeby tego krótkiego wprowadzenia wybierz 30 dni. (Filtry czasowe działają też w przypadku jednorazowego dostępu).
Po wyrażeniu zgody i określeniu czasu trwania dostępu powinieneś zostać przekierowany do adresu URI przekierowania – https://google.com. Adres URL wygenerowany w pasku adresu zawiera token dostępu OAuth.

Jeśli na przykład konto użytkownika przyznaje dostęp OAuth do zakresu dataportability.myactivity.search, wygenerowany adres URL będzie wyglądał tak:
```
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
```
W adresie URL ciąg your_OAuth_token reprezentuje token.

Ważne: token dostępu OAuth wygasa po 1 godzinie. Jeśli musisz wygenerować nowy token, wykonaj poprzednie czynności.
Aby zweryfikować token OAuth, wklej ten adres URL w przeglądarce:
```
https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token
```
Odpowiedź powinna wyglądać tak:
```
{
  "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"
}
```
Aby wysyłać żądania, nie musisz używać pól azp ani aud. Pole azp reprezentuje client_id autoryzowanej aplikacji prezentującej token, a pole aud identyfikuje odbiorcę, dla którego jest przeznaczony dany token. Będzie on równy jednemu z identyfikatorów klienta Twojej aplikacji.

Uwaga: token możesz też zweryfikować, wysyłając żądanie HTTP GET.
Uzyskaj token OAuth i klucz interfejsu API. Potrzebujesz ich do wywoływania interfejsu Data Portability API.

Wysyłanie żądań do punktów końcowych

W tym krótkim wprowadzeniu używasz poleceń curl do wywoływania punktów końcowych interfejsu Data Portability API z dodatkiem sygnatur czasowych, aby filtrować eksportowane dane.Te polecenia wymagają wcześniej zebranego tokena OAuth i klucza API.

Dane z ostatniego eksportu

Aby wyeksportować nowe dane od ostatniego eksportu, możesz użyć filtrów czasowych z dostępem czasowym. Rozważ na przykład zakreshttps://www.googleapis.com/auth/dataportability.myactivity.search.

Najpierw wysyłasz uwierzytelnione żądanie do punktu końcowego InitiatePortabilityArchive. To żądanie uruchamia zadanie archiwizowania całego zbioru danych.

Uruchom to polecenie 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
```
W tym poleceniu:
- your_OAuth_token to Twój token OAuth.
Ostrzeżenie: parametr resources powinien zawierać tylko te zakresy uprawnień OAuth, które mają przyznany dostęp i obsługują filtry czasowe. W tym przykładzie przyznano tylko uprawnienie myactivity.search. Jeśli uwzględnisz dodatkowe grupy zasobów lub grupy zasobów, które nie są obsługiwane, zwrócony zostanie błąd. Więcej informacji znajdziesz w sekcji Ograniczenia zakresu.

Żądanie InitiatePortabilityArchive zwraca archiveJobId i accessType. Identyfikator zadania służy do pobierania stanu archiwum danych, a typ dostępu określa, czy masz jednorazowy czy czasowy dostęp do danych. W przypadku dostępu na podstawie czasu zobaczysz:
```
{
  "archiveJobId": "<your_job_id_1>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Jeśli nie podasz prawidłowego tokena OAuth, zwróci się ten komunikat o błędzie:
```
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.
```
Następnie wysyłasz uwierzytelnione żądanie do punktu końcowego GetPortabilityArchiveState, aby pobrać stan zadania archiwizacji.

Uruchom to polecenie 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_1/portabilityArchiveState
```
W tym poleceniu:
- your_OAuth_token to Twój token OAuth.
- your_job_id_1 to identyfikator zadania zwrócony przez żądanie InitiatePortabilityArchive.
Odpowiedź zależy od stanu zadania. Jeśli zadanie nie zostało ukończone, odpowiedź zawiera jego bieżący stan. Do tego punktu końcowego należy okresowo wysyłać żądania, aż do zakończenia zadania.
```
{
  "state": "IN_PROGRESS"
}
```
Jeśli zadanie zostało ukończone, odpowiedź zawiera stan i co najmniej 1 adres URL podpisany cyfrowo, który służy do pobrania archiwum danych. Jest też pole export_time, które zawiera sygnaturę czasową pierwszego wywołania funkcji InitiatePortabilityArchive.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}
```
Aby pobrać archiwum danych, wklej podpisany adres URL w przeglądarce. Sprawdź zawartość archiwum, aby się upewnić, że zawiera ono oczekiwane dane o aktywności wyszukiwania.

Uwaga: czas potrzebny na wykonanie zadania archiwizacji zależy od rozmiaru archiwum. Maksymalny czas trwania to 7 dni.

Jeśli w odpowiedzi otrzymasz stan FAILED, możesz ponownie spróbować wyeksportować dane, używając metody RetryPortabilityArchive.
Odczekaj co najmniej 24 godziny, a potem prześlij kolejną prośbę do InitiatePortabilityArchive, używając tego samego polecenia co w kroku 1, ale tym razem z wartością export_time zamiast start_time.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": timestamp_of_first_initiate_request}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Uwaga: możesz dostosować start_time tak, aby nieco zachodziło na export_time, aby mieć pewność, że dane wygenerowane między żądaniami zostaną uwzględnione w eksporcie.

W przypadku dostępu czasowego funkcja ta zwróci:
```
{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Powtórz krok 2, aby wysłać uwierzytelnione żądanie do punktu końcowego GetPortabilityArchiveState w celu pobrania stanu zadania archiwizacji (za pomocą <your_job_id_2>).

Po zakończeniu zadania odpowiedź będzie wyglądać tak:

  {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

Sprawdź, czy dane w drugim eksporcie zawierają tylko nowe dane wygenerowane po pierwszym eksporcie.

Dane z ostatnich 6 miesięcy

Możesz też użyć filtrów czasowych, aby wyeksportować tylko najnowsze dane zamiast całego zbioru.

Załóżmy, że dziś jest 2024-10-01 i chcesz wyeksportować dane z ostatnich 6 miesięcy. Najpierw wysyłasz uwierzytelnione żądanie do punktu końcowego InitiatePortabilityArchive z start_time „2024-04-01T00:00:00Z”.

Uruchom to polecenie curl:

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2024-04-01T00:00:00Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

W przypadku dostępu czasowego funkcja ta zwróci:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Prześlij żądanie do punktu końcowego GetPortabilityArchiveState, aby pobrać stan zadania archiwizacji.

Uruchom to polecenie curl:
```
curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/job_id_1/portabilityArchiveState
```
Po zakończeniu zadania odpowiedź będzie wyglądać tak:
```
{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}
```
Pamiętaj, że start_time to parametr start_time podany w kroku 1, a export_time to sygnatura czasowa wywołania funkcji InitiatePortabilityArchive w kroku 1.
Sprawdź, czy eksport zawiera tylko dane z ostatnich 6 miesięcy.

Dane z określonego okresu

Za pomocą filtrów czasowych możesz eksportować dane z określonego zakresu dat, np. tylko z 2023 r.

Najpierw wysyłasz uwierzytelnione żądanie do punktu końcowego InitiatePortabilityArchive z start_time „2023-01-01T00:00:00Z” i end_time „2023-12-31T23:59:59Z”.

Uruchom to polecenie curl:

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

W przypadku dostępu czasowego funkcja ta zwróci:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Prześlij żądanie do punktu końcowego GetPortabilityArchiveState, aby pobrać stan zadania archiwizacji.

Uruchom to polecenie curl:

curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/job_id_1/portabilityArchiveState

Po zakończeniu zadania odpowiedź będzie wyglądać tak:

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

Pamiętaj, że start_time to wartość start_time określona w kroku 1, a export_time jest równa wartości end_time podanej w kroku 1.

Sprawdź, czy eksport zawiera tylko dane z 2023 r.

Obsługiwane zakresy

Filtry czasowe obsługują te zakresy:

https://www.googleapis.com/auth/dataportability.myactivity.youtube
https://www.googleapis.com/auth/dataportability.myactivity.maps
https://www.googleapis.com/auth/dataportability.myactivity.search
https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
https://www.googleapis.com/auth/dataportability.myactivity.shopping
https://www.googleapis.com/auth/dataportability.myactivity.play
https://www.googleapis.com/auth/dataportability.chrome.history

Uwaga: żądania z filtrem czasowym, które łączą obsługiwane i nieobsługiwane zakresy, powodują błąd INVALID_ARGUMENT o treść The requested resources do not support time filters.