Google Cloud Platform'da (GCP) Toplama Hizmeti ile Çalışma

1. 1. Ön koşullar

Tahmini tamamlama süresi: 1-2 saat

Bu kod laboratuvarını gerçekleştirmenin 2 modu vardır: Yerel Test veya Toplama Hizmeti. Yerel test modu için yerel bir makine ve Chrome tarayıcı gerekir (Google Cloud kaynağı oluşturma/kullanımı yoktur). Aggregation Service modu, Aggregation Service'in Google Cloud'da tam olarak dağıtılmasını gerektirir.

Bu codelab'i iki moddan birinde gerçekleştirmek için birkaç ön koşulu karşılamanız gerekir. Her şart, Yerel Test veya Toplama Hizmeti için gerekli olup olmadığına göre işaretlenir.

1.1. Kayıt ve Onay İşlemini Tamamlama (Aggregation Service)

Özel Korumalı Alan API'lerini kullanmak için hem Chrome hem de Android için Kayıt ve Onay işlemlerini tamamladığınızdan emin olun.

1.2. Reklam gizliliği API'lerini (Yerel Test ve Toplama Hizmeti) etkinleştirme

Özel Korumalı Alan'ı kullanacağımız için Özel Korumalı Alan reklam API'lerini etkinleştirmenizi öneririz.

Tarayıcınızda chrome://settings/adPrivacy adresine gidin ve tüm reklam gizliliği API'lerini etkinleştirin.

Ayrıca üçüncü taraf çerezlerinizin etkinleştirildiğinden emin olun.

chrome://settings/cookies adresinde üçüncü taraf çerezlerinin ENGELLENMEDİĞİNDEN emin olun. Chrome sürümünüze bağlı olarak bu ayarlar menüsünde farklı seçenekler görebilirsiniz. Ancak kabul edilen yapılandırmalar şunlardır:

• "Tüm üçüncü taraf çerezlerini engelle" = ENGELLENDİ
• "Üçüncü taraf çerezlerini engelle" = DEVRE DIŞI
• "Gizli modda üçüncü taraf çerezleri engelle" = ETMEK

Bu ayarın geçerli olması için Chrome'u yeniden başlatmanız gerekir.

1.3. Yerel Test Aracı'nı indirme (Yerel Test)

Yerel test için Yerel Test Aracı'nın indirilmesi gerekir. Araç, şifrelenmemiş hata ayıklama raporlarından özet raporlar oluşturur.

Yerel test aracı, GitHub'daki Cloud Functions JAR Arşivleri'nden indirilebilir. Dosya LocalTestingTool_{version}.jar olarak adlandırılmalıdır.

1.4. JAVA JRE'nin yüklü olduğundan emin olun (Yerel Test ve Toplama Hizmeti)

"Terminal"i açın ve makinenizde Java veya openJDK'nın yüklü olup olmadığını kontrol etmek için java --version simgesini kullanın.

Yüklü değilse Java sitesinden veya openJDK sitesinden indirip yükleyebilirsiniz.

1.5. aggregatable_report_converter (Yerel Test ve Toplama Hizmeti) dosyasını indirin

aggregatable_report_converter'ın bir kopyasını Privacy Sandbox Demos GitHub deposundan indirebilirsiniz. GitHub deposunda IntelliJ veya Eclipse'in kullanılmasından bahsedilir ancak bunların kullanılması zorunlu değildir. Bu araçları kullanmıyorsanız JAR dosyasını yerel ortamınıza indirin.

1.6. GCP ortamı (Aggregation Service) oluşturma

Toplama Hizmeti, bulut sağlayıcı kullanan Güvenilir Yürütme Ortamı'nın kullanılmasını gerektirir. Bu codelab'de toplama hizmeti GCP'de dağıtılacak ancak AWS de desteklenir.

gcloud CLI'yi ayarlamak, Terraform ikili dosyalarını ve modüllerini indirmek ve Toplama Hizmeti için GCP kaynakları oluşturmak üzere GitHub'daki Dağıtım Talimatlarını uygulayın.

Önemli not: Hizmeti dağıtmak için belirli izinlere ihtiyacınız vardır. Bu kod laboratuvarının çalışması için kullanıcının GCP projesinde Yönetici Erişimi / Sahip iznine sahip olduğundan emin olun.

Dağıtım Talimatlarındaki temel adımlar:

1. Ortamınızda "gcloud" CLI'yi ve Terraform'u ayarlayın.
2. Terraform durumunu depolamak için bir Cloud Storage paketi oluşturun.
3. Bağımlılıkları indirin.
4. adtech_setup.auto.tfvars dosyasını güncelleyin ve adtech_setup Terraform'u çalıştırın. Örnek adtech_setup.auto.tfvars dosyası için Ek'e bakın. Burada oluşturulan veri paketinin adını not edin. Bu ad, oluşturduğumuz dosyaları depolamak için codelab'de kullanılır.
5. dev.auto.tfvars dosyasını güncelleyin, dağıtım hizmet hesabının kimliğine bürünün ve dev Terraform'u çalıştırın. Örnek dev.auto.tfvars dosyası için Ek'e bakın.
6. Dağıtım tamamlandıktan sonra, sonraki adımlarda Toplama Hizmeti'ne istek göndermek için gereken frontend_service_cloudfunction_url değerini Terraform çıkışından alın.

1.7. Aggregation Service ilk katılımını tamamlama (Aggregation Service)

Toplama Hizmeti'nin kullanılabilmesi için koordinatörlerin oryantasyon eğitimini tamamlaması gerekir. Raporlama sitenizi ve diğer bilgileri sağlayarak, "Google Cloud"u seçerek ve hizmet hesabı adresinizi girerek Toplama Hizmeti İlk Katılım Formu'nu doldurun. Bu hizmet hesabı, önceki ön koşulda (1.6. GCP ortamı oluşturma). (İpucu: Sağlanan varsayılan adları kullanırsanız bu hizmet hesabı "işçi-sa@" ile başlar.)

İlk katılım sürecinin tamamlanması 2 haftayı bulabilir.

1.8. API uç noktalarını çağırma yönteminizi belirleme (Toplama Hizmeti)

Bu kod laboratuvarında, Toplama Hizmeti API uç noktalarını çağırmanız için 2 seçenek sunulur: cURL ve Postman. cURL, minimum kurulum gerektirdiği ve ek yazılım gerektirmediği için API uç noktalarını Terminal'inizden çağırmanın daha hızlı ve kolay bir yoludur. Ancak cURL kullanmak istemiyorsanız API isteklerini yürütmek ve gelecekte kullanmak üzere kaydetmek için Postman'ı kullanabilirsiniz.

3.2 numaralı bölümde. Toplama Hizmeti Kullanımı başlıklı makalede her iki seçeneğin de kullanımıyla ilgili ayrıntılı talimatlar bulabilirsiniz. Hangi yöntemi kullanacağınızı belirlemek için bunları şimdi önizleyebilirsiniz. Postman'ı seçerseniz aşağıdaki ilk kurulumu yapın.

1.8.1. Çalışma alanını ayarlama

Postman hesabına kaydolun. Kaydolduktan sonra sizin için otomatik olarak bir Workspace alanı oluşturulur.

Sizin için bir çalışma alanı oluşturulmamışsa üst gezinme menüsündeki "Çalışma alanları"na gidin ve "Çalışma alanı oluştur"u seçin.

"Boş çalışma alanı"nı seçin, sonrakini tıklayın ve çalışma alanına "GCP Privacy Sandbox" adını verin. "Kişisel"i seçin ve "Oluştur"u tıklayın.

Önceden yapılandırılmış çalışma alanı JSON yapılandırmasını ve Küresel Ortam dosyalarını indirin.

"İçe aktar" düğmesini kullanarak her iki JSON dosyasını da "Workspace'im"e aktarın.

Bu işlem, createJob ve getJob HTTP istekleriyle birlikte "GCP Privacy Sandbox" koleksiyonunu oluşturur.

1.8.2. Yetkilendirme kurulumu

"GCP Privacy Sandbox" koleksiyonunu tıklayın ve "Authorization" (Yetkilendirme) sekmesine gidin.

"Taşıyıcı jetonu" yöntemini kullanırsınız. Terminal ortamınızda bu komutu çalıştırın ve çıkışı kopyalayın.

gcloud auth print-identity-token

Ardından bu jeton değerini Postman yetkilendirme sekmesinin "Jeton" alanına yapıştırın:

1.8.3. Ortamı ayarlama

Sağ üst köşedeki "Ortama hızlı bakış"a gidin:

"Düzenle"yi tıklayın ve "environment", "region" ve "cloud-function-id" için "Mevcut Değer"i güncelleyin:

"request-id" parametresini daha sonra dolduracağımız için şimdilik boş bırakabilirsiniz. Diğer alanlar için, 1.6 ön koşulunda Terraform dağıtımının başarıyla tamamlanmasından döndürülen frontend_service_cloudfunction_url içindeki değerleri kullanın. URL şu biçimde olmalıdır: https://--frontend-service--uc.a.run.app

2. 2. Yerel Test Codelab'i

Tahmini tamamlama süresi: <1 saat

Şifrelenmemiş hata ayıklama raporlarını kullanarak toplama işlemi yapmak ve özet raporlar oluşturmak için makinenizdeki yerel test aracını kullanabilirsiniz. Başlamadan önce, "Yerel Test" etiketli tüm ön koşulları tamamladığınızdan emin olun.

Codelab adımları

2.1. adım. Raporu tetikle: Raporu toplayabilmek için Gizli Toplama raporlamasını tetikleyin.

2.2. adım. Hata ayıklama AVRO raporu oluşturma: Toplanan JSON raporunu AVRO biçimli bir rapora dönüştürün. Bu adım, reklam teknolojilerinin raporları API raporlama uç noktalarından toplayıp JSON raporları AVRO biçimli raporlara dönüştürmesine benzer.

2.3. adım. Paket anahtarlarını alma: Paket anahtarları reklam teknolojisi şirketleri tarafından tasarlanır. Bu kod laboratuvarındaki paketler önceden tanımlandığından, paket anahtarlarını sağlandığı şekilde alın.

2.4. adım. Çıkış alanı AVRO dosyasını oluşturun: Paket anahtarları alındıktan sonra çıkış alanı AVRO dosyasını oluşturun.

2,5.adım. Özet Rapor Oluşturma: Yerel Ortamda Özet Rapor oluşturmak için Yerel Test Aracı'nı kullanın.

2.6. adım. Özet raporları inceleyin: Yerel test aracı tarafından oluşturulan özet raporu inceleyin.

2.1. Tetikleyici raporu

Gizli toplama raporunu tetiklemek için Özel Korumalı Alan demo sitesini (https://privacy-sandbox-demos-news.dev/?env=gcp) veya kendi sitenizi (ör. https://adtechexample.com) kullanabilirsiniz. Kendi sitenizi kullanıyorsanız ve Kayıt, Onaylama ve Toplama Hizmeti İlk Kayıt işlemini tamamlamadıysanız Chrome işareti ve CLI anahtarı kullanmanız gerekir.

Bu demo için Özel Korumalı Alan demo sitesini kullanacağız. Siteye gitmek için bağlantıyı takip edin. Ardından, raporları chrome://private-aggregation-internals adresinde görüntüleyebilirsiniz:

{reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage uç noktasına gönderilen rapor, Chrome Dahili sayfasında gösterilen raporların "Rapor Gövdesi"nde de bulunur.

Burada birçok rapor görebilirsiniz ancak bu kod laboratuvarında, GCP'ye özgü olan ve hata ayıklama uç noktası tarafından oluşturulan birleştirilebilir raporu kullanın. "Rapor URL'si" "/debug/" içerir ve "Rapor Gövdesi"nin aggregation_coordinator_origin field şu URL'yi içerir: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Not: Yukarıda gösterilen gibi bir hata ayıklama raporu görmüyorsanız Özel Korumalı Alan demo sayfasını, ardından Chrome'un iç işleyişine ilişkin sayfayı yenileyin. Hata ayıklama uç noktası tarafından oluşturulan rapor da dahil olmak üzere daha fazla rapor görürsünüz. Aksi takdirde üçüncü taraf çerezlerinin etkinleştirildiğinden emin olun.

2.2. Toplanabilir Hata Ayıklama Raporu Oluşturma

chrome://private-aggregation-internals'ün "Rapor Gövdesi"nde bulunan raporu kopyalayın ve privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar klasöründe (1.5 ön koşulunda indirilen depo içinde) bir JSON dosyası oluşturun.

Bu örnekte, Linux kullandığımız için vim kullanıyoruz. Ancak istediğiniz metin düzenleyiciyi kullanabilirsiniz.

vim report.json

Raporu report.json içine yapıştırın ve dosyanızı kaydedin.

Bu işlemi tamamladıktan sonra, hata ayıklama için birleştirilebilir raporu oluşturmak üzere aggregatable_report_converter.jar simgesini kullanın. Bu işlem, mevcut dizininizde report.avro adlı toplanabilir bir rapor oluşturur.

java -jar aggregatable_report_converter.jar \
  --request_type convertToAvro \
  --input_file report.json \
  --debug

2.3. Rapordan Paket Anahtarını Alma

output_domain.avro dosyasını oluşturmak için raporlardan alınabilecek paket anahtarlarına ihtiyacınız vardır.

Grup anahtarları reklam teknolojisi tarafından tasarlanır. Ancak bu durumda, Privacy Sandbox Demo sitesi paket anahtarlarını oluşturur. Bu site için gizli toplama hata ayıklama modunda olduğundan, paket anahtarını almak için "Rapor Gövdesi"ndeki debug_cleartext_payload değerini kullanabiliriz.

Rapor gövdesinden debug_cleartext_payload öğesini kopyalayın.

goo.gle/ags-payload-decoder adresini açın, debug_cleartext_payload dosyanızı "GİRİŞ" kutusuna yapıştırın ve "Kod çöz"ü tıklayın.

Sayfa, paket anahtarının ondalık değerini döndürür. Aşağıda örnek bir paket anahtarı verilmiştir.

2.4. Çıkış Alanı AVRO Oluşturma

Paket anahtarına sahip olduğumuza göre, üzerinde çalıştığımız klasörde output_domain.avro dosyasını oluşturalım. Bucket anahtarını, aldığınız bucket anahtarıyla değiştirdiğinizden emin olun.

java -jar aggregatable_report_converter.jar \
  --request_type createDomainAvro \
  --bucket_key <bucket key>

Komut dosyası, output_domain.avro dosyasını mevcut klasörünüzde oluşturur.

2.5. Yerel Test Aracı'nı kullanarak özet raporlar oluşturma

Aşağıdaki komutu kullanarak özet raporlar oluşturmak için 1.3 ön koşulunda indirilen LocalTestingTool_{version}.jar dosyasını kullanacağız. {version} kısmını indirdiğiniz sürümle değiştirin. LocalTestingTool_{version}.jar dosyasını geçerli dizine taşımayı veya mevcut konumuna referans vermek için göreli bir yol eklemeyi unutmayın.

java -jar LocalTestingTool_{version}.jar \
  --input_data_avro_file report.avro \
  --domain_avro_file output_domain.avro \
  --output_directory .

Komut çalıştırıldığında aşağıdakine benzer bir mesaj görürsünüz. Bu işlem tamamlandığında bir rapor output.avro oluşturulur.

2.6. Özet raporu inceleme

Oluşturulan özet rapor AVRO biçimindedir. Bunu okuyabilmek için AVRO'dan JSON biçimine dönüştürmeniz gerekir. İdeal olarak, reklam teknolojisi AVRO raporlarını JSON'a dönüştürecek kod yazmalıdır.

AVRO raporunu JSON'a dönüştürmek için aggregatable_report_converter.jar'ü kullanacağız.

java -jar aggregatable_report_converter.jar \
  --request_type convertToJson \
  --input_file output.avro

Bu işlem, aşağıdakine benzer bir rapor döndürür. Aynı dizinde oluşturulan bir output.json raporu da eklenir.

Codelab tamamlandı.

Özet: Bir hata ayıklama raporu topladınız, bir çıkış alanı dosyası oluşturdunuz ve Aggregation Service'in toplama davranışını simüle eden yerel test aracını kullanarak bir özet raporu oluşturdunuz.

Sonraki adımlar: Yerel test aracını denediğinize göre, aynı denemeyi kendi ortamınızdaki bir toplama hizmeti canlı dağıtımıyla deneyebilirsiniz. Her şeyi "Toplama Hizmeti" modu için ayarladığınızdan emin olmak üzere ön koşulları tekrar inceleyin, ardından 3. adıma geçin.

3. 3. Aggregation Service Codelab

Tahmini tamamlama süresi: 1 saat

Başlamadan önce, "Toplama Hizmeti" etiketli tüm ön koşulları tamamladığınızdan emin olun.

Codelab adımları

3.1. adım. Aggregation Service Giriş Oluşturma: Aggregation Service için toplu olarak oluşturulan Aggregation Service raporlarını oluşturun.

• 3.1.1.adım Tetikleyici Raporu
• 3.1.2.adım Toplanabilir Raporlar Toplama
• 3.1.3.adım Raporları AVRO'ya dönüştürme
• 3.1.4.adım output_domain AVRO'yu oluşturma
• 3.1.5.adım Raporları Cloud Storage paketine taşıma

3.2. adım. Aggregation Service Kullanımı: Özet raporlar oluşturmak ve özet raporları incelemek için Aggregation Service API'yi kullanın.

• 3.2.1.adım Grup oluşturmak için createJob uç noktasını kullanma
• 3.2.2.adımı Grup durumunu almak için getJob uç noktasını kullanma
• 3.2.3.adım Özet raporu inceleme

3.1. Toplama Hizmeti Giriş Oluşturma

Toplama hizmetine toplu olarak göndermek için AVRO raporlarını oluşturmaya devam edin. Bu adımlardaki kabuk komutları, GCP'nin Cloud Shell'inde (Ön Koşullar'daki bağımlılıklar Cloud Shell ortamınıza klonlandığı sürece) veya yerel bir yürütme ortamında çalıştırılabilir.

3.1.1. Tetikleyici Raporu

Siteye gitmek için bağlantıyı takip edin. Ardından, raporları chrome://private-aggregation-internals adresinde görüntüleyebilirsiniz:

{reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage uç noktasına gönderilen rapor, Chrome Dahili sayfasında gösterilen raporların "Rapor Gövdesi"nde de bulunur.

Burada birçok rapor görebilirsiniz ancak bu kod laboratuvarında, GCP'ye özgü olan ve hata ayıklama uç noktası tarafından oluşturulan birleştirilebilir raporu kullanın. "Rapor URL'si" "/debug/" içerir ve "Rapor Gövdesi"nin aggregation_coordinator_origin field şu URL'yi içerir: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Not: Yukarıda gösterilen gibi bir hata ayıklama raporu görmüyorsanız Özel Korumalı Alan demo sayfasını, ardından Chrome'un dahili sayfasını yenileyin. Hata ayıklama uç noktası tarafından oluşturulan rapor da dahil olmak üzere daha fazla rapor görürsünüz. Aksi takdirde üçüncü taraf çerezlerinin etkinleştirildiğinden emin olun.

3.1.2. Toplanabilir Raporlar Toplama

Toplanabilir raporlarınızı, ilgili API'nizin .well-known uç noktalarından toplayın.

• Private Aggregation: {reporting-origin}/.well-known/private-aggregation/report-shared-storage
• İlişkilendirme Raporları - Özet Raporu: {reporting-origin}/.well-known/attribution-reporting/report-aggregate-attribution

Bu kod laboratuvarında rapor toplama işlemini manuel olarak gerçekleştiririz. Üretimde, reklam teknolojilerinin raporları programatik olarak toplayıp dönüştürmesi beklenir.

Şimdi chrome://private-aggregation-internals adresindeki "Rapor Gövdesi"ne JSON raporunu kopyalayalım.

Bu örnekte, Linux kullandığımız için vim kullanıyoruz. Ancak istediğiniz metin düzenleyiciyi kullanabilirsiniz.

vim report.json

Raporu report.json içine yapıştırın ve dosyanızı kaydedin.

3.1.3. Raporları AVRO'ya dönüştürme

.well-known uç noktalarından alınan raporlar JSON biçimindedir ve AVRO rapor biçimine dönüştürülmesi gerekir. JSON raporunu aldıktan sonra report.json'ün depolandığı yere gidin ve toplanabilir hata ayıklama raporu oluşturmak için aggregatable_report_converter.jar'ü kullanın. Bu işlem, mevcut dizininizde report.avro adlı toplanabilir bir rapor oluşturur.

java -jar aggregatable_report_converter.jar \
  --request_type convertToAvro \
  --input_file report.json

3.1.4. output_domain AVRO'yu oluşturma

output_domain.avro dosyasını oluşturmak için raporlardan alınabilecek paket anahtarlarına ihtiyacınız vardır.

Grup anahtarları reklam teknolojisi tarafından tasarlanır. Ancak bu durumda, Privacy Sandbox Demo sitesi paket anahtarlarını oluşturur. Bu site için gizli toplama hata ayıklama modunda olduğundan, paket anahtarını almak için "Rapor Gövdesi"ndeki debug_cleartext_payload değerini kullanabiliriz.

Rapor gövdesinden debug_cleartext_payload öğesini kopyalayın.

goo.gle/ags-payload-decoder adresini açın, debug_cleartext_payload dosyanızı "GİRİŞ" kutusuna yapıştırın ve "Kod çöz"ü tıklayın.

Sayfa, paket anahtarının ondalık değerini döndürür. Aşağıda örnek bir paket anahtarı verilmiştir.

Paket anahtarına sahip olduğumuza göre, üzerinde çalıştığımız klasörde output_domain.avro dosyasını oluşturalım. Bucket anahtarını, aldığınız bucket anahtarıyla değiştirdiğinizden emin olun.

java -jar aggregatable_report_converter.jar \
  --request_type createDomainAvro \
  --bucket_key <bucket key>

Komut dosyası, output_domain.avro dosyasını mevcut klasörünüzde oluşturur.

3.1.5. Raporları Cloud Storage paketine taşıma

AVRO raporları ve çıkış alanı oluşturulduktan sonra raporları ve çıkış alanını Cloud Storage'daki pakete (1.6 ön koşulunda belirttiğiniz) taşımaya devam edin.

Yerel ortamınızda gcloud KSA kuruluysa dosyaları ilgili klasörlere kopyalamak için aşağıdaki komutları kullanın.

gcloud storage cp report.avro gs://<bucket_name>/reports/

gcloud storage cp output_domain.avro gs://<bucket_name>/output_domain/

Aksi takdirde dosyaları paketinize manuel olarak yükleyin. "Raporlar" adlı bir klasör oluşturun ve report.avro dosyasını bu klasöre yükleyin. "output_domains" adlı bir klasör oluşturun ve output_domain.avro dosyasını bu klasöre yükleyin.

3.2. Toplama Hizmeti Kullanımı

1.8 ön koşulunda, Toplama Hizmeti uç noktalarına API isteği göndermek için cURL veya Postman'ı seçtiğinizi hatırlayın. Aşağıda her iki seçenekle ilgili talimatları bulabilirsiniz.

İşiniz bir hatayla başarısız olursa nasıl devam edeceğiniz hakkında daha fazla bilgi için GitHub'daki sorun giderme dokümanlarımızı inceleyin.

3.2.1. Grup oluşturmak için createJob uç noktasını kullanma

Bir iş oluşturmak için aşağıdaki cURL veya Postman talimatlarını kullanın.

cURL

"Terminal"inizde bir istek gövdesi dosyası (body.json) oluşturun ve aşağıdaki metni yapıştırın. Yer tutucu değerleri güncellediğinizden emin olun. Her alanın neyi temsil ettiği hakkında daha fazla bilgi için bu API dokümanlarına bakın.

Not: Mümkünse attribution_report_to yerine job_parameters içinde tanımlanan reporting_site değerini kullanmanızı öneririz. attribution_report_to alanı, Aggregation Service API arayüzünün bir sonraki büyük sürüm yükseltmesinde kullanımdan kaldırılacak. (Daha fazla bilgi) reporting_site parametresi, dağıtılmış bir alan adı altında birden fazla kaynak kullanmanıza olanak tanır. attribution_report_to ise tek sunucu kaynağını destekler. reporting_site için geçerli bir dize değeri https://example-dsp-host.com olabilir. Bu değer, https://dspp-a.example-dsp-host.com veya https://dspp-b.example-dsp-host.com gibi raporlama kaynaklarını kapsar. Öte yandan, attribution_report_to için örnek bir değer https://dsp-a.example-dsp-host.com veya https://privacy-sandbox-demos-dsp.dev olur. Toplama Hizmeti oryantasyonu sırasında sağladığınız raporlama sitelerini (Ön koşul 1.7) unutmayın. (Örneğin: "https://privacy-sandbox-demos-dsp.dev")

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

Aşağıdaki isteği yürütün. cURL isteğinin URL'sindeki yer tutucuları, Önkoşul 1.6'da Terraform dağıtımının başarıyla tamamlanmasından sonra oluşturulan frontend_service_cloudfunction_url değerleriyle değiştirin.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -d @body.json \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/createJob

İstek toplama hizmeti tarafından kabul edildiğinde bir HTTP 202 yanıtı alırsınız. Olası diğer yanıt kodları API özelliklerinde açıklanmıştır.

Postman

createJob uç noktası için, toplama hizmetine birleştirilebilir raporların, çıkış alanlarının ve özet raporların konumunu ve dosya adlarını sağlamak amacıyla bir istek gövdesi gerekir.

createJob isteğinin "Gövde" sekmesine gidin:

Sağlanan JSON'daki yer tutucuları değiştirin. Bu alanlar ve neyi temsil ettikleri hakkında daha fazla bilgi için API belgelerine bakın.

Not: attribution_report_to yerine job_parameters içinde tanımlanan reporting_site değerini kullanmanızı öneririz.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

createJob API isteğini "Gönder":

Yanıt kodunu sayfanın alt yarısında bulabilirsiniz:

İstek toplama hizmeti tarafından kabul edildiğinde bir HTTP 202 yanıtı alırsınız. Olası diğer yanıt kodları API özelliklerinde açıklanmıştır.

3.2.2. Grup durumunu almak için getJob uç noktasını kullanma

İş almak için aşağıdaki cURL veya Postman talimatlarını kullanın.

cURL

Terminalinizde aşağıdaki isteği yürütün. URL'deki yer tutucuları, createJob isteği için kullandığınız URL ile aynı olan frontend_service_cloudfunction_url'deki değerlerle değiştirin. "job_request_id" için createJob uç noktasıyla oluşturduğunuz işin değerini kullanın.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/getJob?job_request_id=<job_request_id>

Sonuç, iş isteğinizin durumunu 200 HTTP durumuyla döndürmelidir. "Body" isteği, job_status, return_message ve error_messages (iş hatayla sona erdiyse) gibi gerekli bilgileri içerir.

Not: Bu kod laboratuvarının çalışmasında kullandığımız rapor, Privacy Sandbox demo sitesinin raporlama kaynağıyla ilişkilidir. Ancak, GCP ortamınızda Toplama Hizmeti'ni kullanmaya başladığınızda kendi raporlama kaynağınızı sağladınız. Rapor, ilk katılımdan farklı bir siteden geldiği için return_code PRIVACY_BUDGET_AUTHORIZATION_ERROR içeren bir yanıt alabilirsiniz. Bu beklenen bir durumdur ve yoksayılabilir.

Postman

İş isteğinin durumunu kontrol etmek için getJob uç noktasını kullanabilirsiniz. getJob isteğinin "Params" bölümünde, job_request_id değerini createJob isteğinde gönderilen job_request_id ile güncelleyin.

getJob isteğini "gönderin":

Sonuç, iş isteğinizin durumunu 200 HTTP durumuyla döndürmelidir. "Body" isteği, job_status, return_message ve error_messages (iş hatayla sona erdiyse) gibi gerekli bilgileri içerir.

Not: Bu kod laboratuvarının çalışmasında kullandığımız rapor, Privacy Sandbox demo sitesinin raporlama kaynağıyla ilişkilidir. Ancak, GCP ortamınızda Toplama Hizmeti'ni kullanmaya başladığınızda kendi raporlama kaynağınızı sağladınız. Rapor, ilk katılımdan farklı bir siteden geldiği için return_code PRIVACY_BUDGET_AUTHORIZATION_ERROR içeren bir yanıt alabilirsiniz. Bu beklenen bir durumdur ve yoksayılabilir.

3.2.3. Özet raporu inceleme

Özet raporunuzu çıkış Cloud Storage paketinize aldıktan sonra yerel ortamınıza indirebilirsiniz. Özet raporlar AVRO biçimindedir ve JSON'a geri dönüştürülebilir. Aşağıdaki komutu kullanarak raporunuzu okumak için aggregatable_report_converter.jar kullanabilirsiniz.

java -jar aggregatable_report_converter.jar \
  --request_type convertToJson \
  --input_file <summary_report_avro>

Bu işlem, her bir paket anahtarının birleştirilmiş değerlerinin aşağıdakine benzer bir JSON'u döndürür.

createJob isteğiniz debug_run değerini doğru olarak içeriyorsa özet raporunuzu output_data_blob_prefix klasöründeki hata ayıklama klasöründe alabilirsiniz. Rapor AVRO biçimindedir ve yukarıdaki komut kullanılarak JSON'a dönüştürülebilir.

Rapor, grup anahtarını, gürültü içermeyen metriği ve özet raporu oluşturmak için gürültü içermeyen metriğe eklenen gürültüyü içerir. Rapor aşağıdakine benzer.

Ek açıklamalarda "in_reports" ve/veya "in_domain" de yer alır. Bu, şu anlama gelir:

• in_reports: Gruplandırma anahtarı, toplanabilir raporlarda kullanılabilir.
• in_domain: Paket anahtarı, output_domain AVRO dosyasında bulunur.

Codelab tamamlandı.

Özet: Toplama Hizmeti'ni kendi bulut ortamınızda dağıttınız, bir hata ayıklama raporu topladınız, bir çıkış alanı dosyası oluşturdunuz, bu dosyaları bir Cloud Storage paketinde depoladınız ve başarılı bir iş çalıştırdınız.

Sonraki adımlar: Ortamınızda Toplama Hizmeti'ni kullanmaya devam edin veya 4. adımdaki temizleme talimatlarını uygulayarak yeni oluşturduğunuz bulut kaynaklarını silin.

4. 4. Temizleme

Terraform aracılığıyla Toplama Hizmeti için oluşturulan kaynakları silmek üzere adtech_setup ve dev (veya diğer ortam) klasörlerindeki destroy komutunu kullanın:

$ cd <repository_root>/terraform/gcp/environments/adtech_setup
$ terraform destroy
$ cd <repository_root>/terraform/gcp/environments/dev
$ terraform destroy

Toplanabilir raporlarınızı ve özet raporlarınızı içeren Cloud Storage paketini silmek için:

$ gcloud storage buckets delete gs://my-bucket

Ayrıca, 1.2 ön koşulundaki Chrome çerez ayarlarınızı önceki durumlarına geri döndürmeyi de seçebilirsiniz.

5. 5. Ek

Örnek adtech_setup.auto.tfvars dosyası

/**
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

project = "my-project-id"

# Required to generate identity token for access of Adtech Services API endpoints
service_account_token_creator_list = ["user:[e-mail]"]

# Uncomment the below line if you like Terraform to create an Artifact registry repository
# for self-build container artifacts. "artifact_repo_location" defaults to "us".
artifact_repo_name     = "my-ags-artifacts"

# Note: Either one of [1] or [2] must be uncommented.

# [1] Uncomment below lines if you like Terraform grant needed permissions to
# pre-existing service accounts
# deploy_service_account_email = "<YourDeployServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"
# worker_service_account_email = "<YourWorkerServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"

# [2] Uncomment below lines if you like Terraform to create service accounts
# and needed permissions granted e.g "deploy-sa" or "worker-sa"
deploy_service_account_name = "deploy-sa"
worker_service_account_name = "worker-sa"
# Uncomment the below line if you want Terraform to create the
# below bucket. "data_bucket_location" defaults to "us".
data_bucket_name     = "my-ags-data"

# Uncomment the below lines if you want to specify service account customer role names
# deploy_sa_role_name = "<YourDeploySACustomRole>"
# worker_sa_role_name = "<YourWorkerSACustomRole>"

Örnek dev.auto.tfvars dosyası

/**
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

# Example values required by job_service.tf
#
# These values should be modified for each of your environments.
region      = "us-central1"
region_zone = "us-central1-c"

project_id  = "my-project-id"
environment = "operator-demo-env"

# Co-locate your Cloud Spanner instance configuration with the region above.
# https://cloud.google.com/spanner/docs/instance-configurations#regional-configurations
spanner_instance_config = "regional-us-central1"

# Adjust this based on the job load you expect for your deployment.
# Monitor the spanner instance utilization to decide on scale out / scale in.
# https://console.cloud.google.com/spanner/instances
spanner_processing_units = 100

# Uncomment the line below at your own risk to disable Spanner database protection.
# This needs to be set to false and applied before destroying all resources is possible.
spanner_database_deletion_protection = false

instance_type = "n2d-standard-8" # 8 cores, 32GiB

# Container image location that packages the job service application
# If not set otherwise, uncomment and edit the line below:
#worker_image = "<location>/<project>/<repository>/<image>:<tag or digest>"

# Service account created and onboarded for worker
user_provided_worker_sa_email = "[e-mail]"

min_worker_instances = 1
max_worker_instances = 20