Data Portability API'yi kullanmaya başlayın

Bu hızlı başlangıç kılavuzunda, hesabınız için bir OAuth jetonu alır ve Veri Taşıma API uç noktalarına tek seferlik istekler gönderirsiniz.

Bu hızlı başlangıç kılavuzunda, kullanıcı verilerine tek seferlik erişim için Data Portability API'nin nasıl kullanılacağı açıklanmaktadır. Kullanıcı verilerine sürekli erişim için Zamana Dayalı Erişimi Kullanma başlıklı makaleyi inceleyin. İsteğinize zaman filtrelerini nasıl uygulayacağınızı öğrenmek için Zaman Filtreleri Uygulama başlıklı makaleyi inceleyin.

Öğrenecekleriniz

Bu hızlı başlangıç kılavuzunda şunları öğreneceksiniz:

• Geçerli bir OAuth jetonu sağlayarak InitiatePortabilityArchive uç noktasına kimliği doğrulanmış bir istek gönderin. Yanıt geçerli bir job_id içermelidir.
• GetPortabilityArchiveState uç noktasına kimliği doğrulanmış bir istek gönderin. Yanıt, geçerli bir iş durumu ve iş tamamlandığında imzalı bir URL içermelidir.
• (İsteğe bağlı) Aynı kimlik bilgilerini kullanarak InitiatePortabilityArchive uç noktasına geçerli bir OAuth jetonu içeren kimliği doğrulanmış bir istek ikinci kez gönderin. Bu işlem, RESOURCE_EXHAUSTED hatası döndürür ve ResetAuthorization uç noktasının önemini vurgulamak için kullanılır.
• ResetAuthorization uç noktasına kimliği doğrulanmış bir istek gönderin. Bu istek, kullanıcı tarafından verilen tüm OAuth kapsamlarını iptal eder.
• (İsteğe bağlı) Daha önce kullandığınız OAuth jetonunu kullanarak InitiatePortabilityArchive uç noktasına istek gönderin. Yetkilendirme sıfırlandıktan sonra istek başarısız olur.

Ön koşullar

Bu hızlı başlangıç kılavuzunu çalıştırmak için:

• Data Portability API'nin bulunduğunuz yerdeki kullanıcılar tarafından kullanılabildiğini doğrulayın. Desteklenen ülke ve bölgelerin listesi için "Verilerinizin bir kopyasını üçüncü taraflarla paylaşma" sayfasındaki Sık Sorulan Sorular bölümüne bakın.
• Data Portability API'nin kurulum adımlarını tamamlayın.
• JavaScript web uygulamaları için OAuth'u yapılandırma adımlarını uygulayın. Üretimde normalde web sunucusu uygulamaları için OAuth akışı gibi farklı bir akış kullanırsınız. Bu hızlı başlangıç kılavuzunda, basitlik açısından JavaScript web uygulaması akışı kullanılmaktadır.
  • Yetkilendirme kimlik bilgilerinizi oluştururken OAuth 2.0 istemci kimliğinizi ve yetkili yönlendirme URI'nizi (ör. https://google.com) not edin. Hızlı başlangıç kılavuzunun ilerleyen bölümlerinde bu bilgilere ihtiyacınız olacaktır.
  • Data Portability API için kapsamları yapılandırırken bu hızlı başlangıç kılavuzunun myactivity.search kaynak grubunu kullandığını unutmayın: https://www.googleapis.com/auth/dataportability.myactivity.search.
  • Erişime izin vermek istediğiniz süreyi seçtiğinizde bu hızlı başlangıç kılavuzu tek seferlik erişim kullanır.
• OAuth jetonu alın.
• Kuruluşunuzun sahibi olduğu veya kontrol ettiği bir hesaba erişme Bu hesaptaki arama etkinliği verileri bu hızlı başlangıç kılavuzunda dışa aktarılır.

OAuth jetonu alma

Bu hızlı başlangıç kılavuzunda, bir URL kullanarak OAuth jetonu almak için yetkilendirme isteği gönderirsiniz. Bu işlem, JavaScript web uygulamaları için akışı kullanır. Bu akış, yenileme jetonu döndürmez.

Üretim uygulaması için genellikle, isteğe bağlı olarak erişim jetonları oluşturmak üzere kullanılabilecek bir yenileme jetonu almak için bir OAuth akışı kullanırsınız. Buna örnek olarak sunucu tarafı web uygulamaları akışı verilebilir.

OAuth jetonu almak için:

1. Aşağıdaki gibi bir URL oluşturun.

   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

   URL'de:

   • client_id, OAuth istemci kimliğinizdir.
   • redirect_uri, yetkilendirilmiş yönlendirme URI'nizdir (ör. https://google.com).

   Bu hızlı başlangıç kılavuzunun URL'sinde arama etkinliği kapsamının kullanıldığına dikkat edin. YouTube etkinliği kapsamını veya her iki kapsamı da kullanabilirsiniz.

   Uyarı: Veri Taşınabilirliği API kapsamlarını diğer kapsam türleriyle karıştırmayın, aynı anda çok fazla kapsam kullanmayın veya daha önce verilmiş kapsamları dahil etmeyin. Aksi takdirde hatalarla karşılaşabilirsiniz. Ayrıntılı bilgi için Kapsam kısıtlamaları başlıklı makaleyi inceleyin.

2. URL'yi tarayıcınızın adres çubuğuna yapıştırın ve OAuth akışında belirtilen adımları uygulayın. Bu akış, bu hızlı başlangıç kılavuzunda kullandığınız, kuruluşunuza ait veya kuruluşunuz tarafından kontrol edilen hesapta oturum açmanızı gerektirir.

   Bu, OAuth kapsamlarına izin veren hesaptır. İzin ekranı şu şekilde görünmelidir (Ekranınızdaki metin bu resimdeki metinden farklı olabilir):

   

3. Erişim izni verilecek kapsamları ve hesabın verilerine erişimi paylaşacağınız süreyi (bir kez, 30 gün veya 180 gün) seçin. Bu hızlı başlangıç kılavuzu için Yalnızca bir kez'i seçin.

4. İzin verdikten ve erişim süresini seçtikten sonra yönlendirme URI'sine (https://google.com) yönlendirilirsiniz. Adres çubuğunda oluşturulan URL, OAuth erişim jetonunu içerir.

   Örneğin, kullanıcı hesabı dataportability.myactivity.search kapsamına OAuth erişimi verirse oluşturulan URL şu şekilde görünür:

   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

   URL'de your_OAuth_token, jetonu temsil eden bir dizedir.

   Önemli: OAuth erişim jetonunuzun süresi bir saat içinde dolar. Yeni bir jeton oluşturmanız gerekiyorsa önceki adımları uygulayın.

5. OAuth jetonunu doğrulamak için bu URL'yi tarayıcınıza yapıştırın:

   https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token

   Yanıt şu şekilde görünmelidir:

   {
     "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"
   }
   

   İstek göndermek için azp veya aud alanlarına ihtiyacınız yoktur. azp alanı, yetkili sunucunun client_id değerini temsil eder. aud alanı ise bu jetonun hedef kitlesini tanımlar. Bu alan, uygulamanızın istemci kimliklerinden birine eşit olur.

   Not: Jetonu HTTP GET isteği göndererek de doğrulayabilirsiniz.

6. OAuth jetonunuzu ve API anahtarınızı alın. Data Portability API'ye çağrı yapmak için bunlara ihtiyacınız vardır.

Uç noktalara istek gönderme

Bu hızlı başlangıç kılavuzunda, Data Portability API uç noktalarını çağırmak için curl komutlarını kullanacaksınız. Bu komutlar için daha önce topladığınız OAuth jetonu ve API anahtarı gerekir.

Data Portability API'yi çağırmak için:

1. Öncelikle InitiatePortabilityArchive uç noktasına kimliği doğrulanmış bir istek gönderirsiniz. Bu istek, bir arşivleme işi başlatır.

   Aşağıdaki curl komutunu çalıştırın:

   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

   Komutta:

   • your_OAuth_token, OAuth jetonunuzdur.
   Uyarı: resources parametresi yalnızca erişim izni verilen OAuth kapsamlarını içermelidir. Bu örnekte yalnızca myactivity.search izni verilmiştir. Ek kaynak grupları eklerseniz hata döndürülür. Ayrıntılı bilgi için Kapsam kısıtlamaları başlıklı makaleyi inceleyin.

   InitiatePortabilityArchive isteği bir job_id ve accessType döndürür. İş kimliği, veri arşivindeki durumu almak için kullanılır ve erişim türü, verilere tek seferlik mi yoksa zamana dayalı erişim mi verildiğini belirler. Bu hızlı başlangıç kılavuzu için tek seferlik erişiminiz olmalıdır.

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

   Geçerli bir OAuth jetonu sağlamazsanız şu hata mesajı döndürülür:

   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. Ardından, arşivleme işinin durumunu almak için GetPortabilityArchiveState uç noktasına kimlik doğrulaması yapılmış bir istek gönderirsiniz.

   Aşağıdaki curl komutunu çalıştırın:

   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

   Komutta:

   • your_OAuth_token, OAuth jetonunuzdur.
   • your_job_id, InitiatePortabilityArchive isteği tarafından döndürülen iş kimliğidir.

   Yanıt, işin durumuna bağlıdır. İş tamamlanmadıysa yanıtta mevcut durum sağlanır. İş tamamlanana kadar bu uç noktaya düzenli olarak istek göndermeniz gerekir.

   {
     "state": "IN_PROGRESS"
   }
   

   İş tamamlandıysa yanıtta durum ve veri arşivini indirmek için kullanılan bir veya daha fazla imzalı URL bulunur.

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

   Veri arşivini indirmek için imzalanmış URL'yi tarayıcınıza yapıştırın. Beklenen arama etkinliği verilerini içerdiğinden emin olmak için arşivin içeriğini incelemeniz gerekir.

   Not: Arşivleme işinin tamamlanması için gereken süre, arşiv boyutuna bağlıdır. Maksimum süre yedi gündür.
   Not: Yanıtta FAILED durumu alırsanız RetryPortabilityArchive yöntemini kullanarak dışa aktarma işlemini yeniden deneyebilirsiniz.

3. (İsteğe bağlı) InitiatePortabilityArchive uç noktasına kimlik doğrulaması yapılmış bir istek göndermek için önceki komutu tekrarlayın.

   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

   Komutta:

   • your_OAuth_token, OAuth jetonunuzdur.

   Yanıt, myactivity.search kaynağı için tek seferlik iznin bu kullanıcı için kullanıldığını belirtmelidir.

   ...
   "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. ResetAuthorization uç noktasına kimliği doğrulanmış bir istek gönderin. Bu istek, kullanıcı tarafından verilen tüm OAuth kapsamlarını iptal eder ve daha önce kullandığınız bir kaynak grubu için InitiatePortabilityArchive çağrısı yapmanıza olanak tanır.

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

   Komutta:

   • your_OAuth_token, OAuth jetonunuzdur.

   Bu komut boş bir yanıt döndürür.

5. (İsteğe bağlı) Yetkilendirmeyi sıfırladıktan sonra InitiatePortabilityArchive uç noktasına başka bir istek gönderin. Daha önce kullandığınız curl komutunu kullanın.

   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

   Komutta:

   • your_OAuth_token, OAuth jetonunuzdur.

   Sağladığınız OAuth jetonu iptal edildiğinden yanıtta bir hata döndürülecektir.

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