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

1. 1. Ön koşullar

Tahmini tamamlama süresi: 1-2 saat

Bu codelab'i gerçekleştirmek için 2 mod vardır: Local Testing (Yerel Test) veya Aggregation Service (Toplama Hizmeti). Yerel Test modu için yerel makine ve Chrome tarayıcı gerekir (Google Cloud kaynağı oluşturma/kullanımı yoktur). Toplama Hizmeti modu, Google Cloud'da Toplama Hizmeti'nin tam dağıtımını gerektirir.

Bu codelab'i her iki modda da gerçekleştirmek için birkaç ön koşul gerekir. Her koşul, Yerel Test veya Toplama Hizmeti için gerekli olup olmadığına göre uygun şekilde işaretlenir.

1.1. Tam Kayıt ve Onay (Toplama Hizmeti)

Özel Korumalı Alan API'lerini kullanmak istiyorsanız hem Chrome hem de Android'de kayıt ve onay sürecini tamamladığınızdan emin olun.

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

Özel Korumalı Alan'ı kullanacağımızdan Özel Korumalı Alan Reklamları API'lerini etkinleştirmenizi öneririz.

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

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

chrome://settings/cookies tarihinden itibaren, üçüncü taraf çerezlerinin engellenmediğinden emin olun. Chrome sürümünüze bağlı olarak, bu ayarlar menüsünde farklı seçenekler görebilirsiniz, ancak kabul edilebilir yapılandırmalar şunlardır:

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

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

1.3. Yerel Test Aracı'nı indirin (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. 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 kullanın.

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

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

aggregatable_report_converter dosyasının bir kopyasını Özel Korumalı Alan Demoları GitHub deposundan indirebilirsiniz. GitHub deposunda IntelliJ veya Eclipse kullanıldığı belirtiliyor, ancak ikisi de zorunlu değil. Bu araçları kullanmıyorsanız JAR dosyasını yerel ortamınıza indirin.

1.6. GCP Ortamı (Toplama Hizmeti) kurma

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

GitHub'da Dağıtım Talimatları'ndaki talimatları uygulayarak gcloud KSA'yı kurun, Terraform ikili programlarını ve modüllerini indirin ve Aggregation Service için GCP kaynakları oluşturun.

Önemli not: Hizmeti dağıtmak için belirli izinlere ihtiyacınız olacaktır. Bu codelab 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. "gcloud"u kurma CLI ve Terraform kullanmanız gerekir.
2. Terraform durumunu depolamak için Cloud Storage paketi oluşturun.
3. Bağımlılıkları indirin.
4. adtech_setup.auto.tfvars uygulaması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, codelab'de oluşturduğumuz dosyaları depolamak için kullanılacaktır.
5. dev.auto.tfvars öğesini güncelleyin, dağıtım hizmet hesabının kimliğine bürünmek 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 gerekli olacak olan frontend_service_cloudfunction_url Terraform çıkışından alın.

1.7. Toplama Hizmeti İlk Katılımı (Toplama Hizmeti)

Toplama Hizmeti, hizmeti kullanabilmek için koordinatörlere ilk katılım gerektirir. Raporlama Sitenizi ve diğer bilgileri sağlayıp "Google Cloud"u seçip hizmet hesabı adresinizi girerek Toplama Hizmeti İlk Katılım formunu doldurun. Bu hizmet hesabı önceki ön koşulda (1.6. GCP Ortamı oluşturabilirsiniz). (İpucu: Sağlanan varsayılan adları kullanırsanız bu hizmet hesabı "worker-sa@" ile başlar.)

İlk katılım sürecinin tamamlanması 2 hafta sürebilir.

1.8. API uç noktalarını çağırmak için yönteminizi belirleyin (Toplama Hizmeti)

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

Bölüm 3.2'de. Toplama Hizmeti Kullanımı'nı seçerseniz iki seçeneği de kullanmaya ilişkin ayrıntılı talimatlar bulacaksınız. Hangi yöntemi kullanacağınızı belirlemek için bunları önizleyebilirsiniz. Postman'i seçerseniz aşağıdaki ilk kurulumu gerçekleştirin.

1.8.1. Çalışma alanı kurulumu

Postman hesabı oluşturun. Kaydolduktan sonra sizin için otomatik olarak bir çalışma alanı oluşturulur.

Sizin için çalışma alanı oluşturulmadıysa "Çalışma alanları"na gidin üst gezinme öğesine gidin ve "Çalışma Alanı Oluştur"u seçin.

"Boş çalışma alanı"nı seçin, İleri'yi tıklayın ve alanı "GCP Özel Korumalı Alan" olarak adlandırın. "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 Genel Ortam dosyalarını indirin.

Her iki JSON dosyasını da "Çalışma Alanım" bölümüne aktarın. "İçe aktar" düğmesi ile düğmesini tıklayın.

Bu işlem, "GCP Özel Korumalı Alan"ı oluşturur sizin için createJob ve getJob HTTP istekleriyle birlikte sunulur.

1.8.2. Yetkilendirme kurulumu

"GCP Özel Korumalı Alan"ı tıklayın. koleksiyonu açın ve "Yetkilendirme"ye gidin sekmesinden yararlanın.

"Hamiline Ait Jeton"u kullanacaksınız yöntemidir. Terminal ortamınızdan bu komutu çalıştırın ve çıkışı kopyalayın.

gcloud auth print-identity-token

Ardından, bu jeton değerini "Token" (Jeton) alanına yapıştırın alanına girin:

1.8.3. Ortamı ayarlama

"Ortam hızlı bakış"a gidin tıklayın:

"Düzenle"yi tıklayın ve "Geçerli Değer"i güncelleyin "environment", "region" ve "cloud-function-id" değerlerini içerir:

"request-id" ifadesini bırakabilirsiniz daha sonra dolduracağımızdan, şimdilik boş bırakın. Diğer alanlar için Ön Koşul 1.6'da Terraform dağıtımının başarıyla tamamlanmasından döndürülen frontend_service_cloudfunction_url değerlerini kullanın. URL şu biçimdedir: https://--frontend-service--uc.a.run.app

2. 2. Yerel Test Codelab'i

Tahmini tamamlanma süresi: 1 saatten az

Toplama yapmak ve şifrelenmemiş hata ayıklama raporlarını kullanarak ö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ı

Adım 2.1. Tetikleyici raporu: Raporu toplayabilmek için Özel Toplama raporlamasını tetikleyin.

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

Adım 2.3. Paket Anahtarlarını Alma: Paket anahtarları, reklam teknolojileri tarafından tasarlanmıştır. Bu codelab'de, paketler önceden tanımlanmış olduğundan paket anahtarlarını sağlandığı şekilde alın.

Adım 2.4. Create Çıkış Alan Adı AVRO: Paket anahtarları alındıktan sonra Çıkış Alanı AVRO dosyasını oluşturun.

Adım 2.5. Özet Rapor Oluşturma: Yerel Ortamda Özet Raporlar oluşturabilmek için Yerel Test Aracı'nı kullanın.

Adım 2.6. Özet Raporları İnceleme: Yerel Test Aracı tarafından oluşturulan Özet Raporu inceleyin.

2.1. Tetikleyici raporu

Özel 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 henüz Kayıt ve Onay ve Toplama Hizmeti İlk Katılımı için bir Chrome işareti ve KSA anahtarı kullanmanız gerekir.

Bu demo için Özel Korumalı Alan demo sitesini kullanacağız. Siteye gitmek için bu bağlantıya gidin; 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, "Rapor Gövdesi"nde de bulunur Chrome Dahili sayfasında görüntülenen raporların sayısı.

Burada çok sayıda rapor görebilirsiniz ancak bu codelab'de, GCP'ye özel ve hata ayıklama uç noktası tarafından oluşturulan toplanabilir raporu kullanın. "Rapor URL'si" "/debug/" ifadesini 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österilene benzer bir hata ayıklama raporu görmüyorsanız Özel Korumalı Alan demo sayfasını yenileyip Chrome dahili sayfasını yenileyin. Hata ayıklama uç noktası tarafından oluşturulan bir rapor da dahil olmak üzere daha fazla rapor göreceksiniz. Ayarlanmadıysa üçüncü taraf çerezlerinin etkin olup olmadığını bir kez daha kontrol edin.

2.2. Hata Ayıklama Toplanabilir Raporu Oluştur

"Rapor Gövdesi"nde bulunan raporu kopyalayın. chrome://private-aggregation-internals adlı dosyanın ve privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar klasöründe bir JSON dosyası oluşturun (Önkoşul 1.5'te indirilen depoda).

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

vim report.json

Raporu report.json alanına yapıştırın ve dosyanızı kaydedin.

Bunu yaptıktan sonra, hata ayıklamayla ilgili toplanabilir raporun oluşturulmasına yardımcı olmak için aggregatable_report_converter.jar öğesini kullanın. Bu işlem, geçerli dizininizde report.avro adında 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ınabilen paket anahtarlarına ihtiyacınız vardır.

Paket anahtarları adTech tarafından tasarlanmıştır. Ancak bu durumda, paket anahtarlarını Özel Korumalı Alan Demosu sitesi oluşturur. Bu site için gizli toplama hata ayıklama modunda olduğundan, "Rapor Gövdesindeki" debug_cleartext_payload öğesini kullanabiliriz. paket anahtarını alın.

Devam edin ve rapor gövdesinden debug_cleartext_payload değerini kopyalayın.

goo.gle/ags-payload-decoder adresini açın ve debug_cleartext_payload dosyanızı "INPUT" bölümüne yapıştırın kutusunu işaretleyin ve "Kodu Çö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

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

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

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

2.5. Yerel Test Aracı'nı kullanarak Özet Raporlar oluşturun

Aşağıdaki komutla özet raporları oluşturmak için Önkoşul 1.3'te indirilen LocalTestingTool_{version}.jar kullanılır. {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ıktan sonra, aşağıdakine benzer bir sonuç görürsünüz. Bu işlem tamamlandığında output.avro adlı bir rapor oluşturulur.

2.6. Özet Raporu inceleme

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

AVRO raporunu tekrar JSON biçimine dönüştürmek için aggregatable_report_converter.jar kullanılır.

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 raporla (output.json) birlikte.

Codelab tamamlandı.

Özet: Yerel test aracını kullanarak bir hata ayıklama raporu topladınız, alan adı dosyası oluşturdunuz ve Toplama Hizmeti'nin toplama davranışını simüle eden yerel test aracını kullanarak özet rapor oluşturdunuz.

Sonraki adımlar: Yerel Test aracıyla deneme yaptığınıza göre artık aynı alıştırmayı kendi ortamınızda Toplama Hizmeti'nin canlı dağıtımıyla deneyebilirsiniz. "Toplama Hizmeti" için her şeyi ayarladığınızdan emin olmak üzere ön koşulları tekrar gözden geçirin moduna geçip 3. adıma geçin.

3. 3. Toplama Hizmeti Codelab'i

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ı

Adım 3.1. Toplama Hizmeti Girişi Oluşturma: Aggregation Service için toplu hale getirilen Toplama Hizmeti raporlarını oluşturun.

• Adım 3.1.1. Tetikleyici Raporu
• Adım 3.1.2. Toplanabilir Raporları Toplama
• Adım 3.1.3. Raporları AVRO'ya Dönüştürme
• Adım 3.1.4. Çıkış_alanı AVRO'su oluştur
• Adım 3.1.5. Raporları Cloud Storage paketine taşıma

Adım 3.2. Toplama Hizmeti Kullanımı: Özet Raporlar oluşturmak ve Özet Raporları incelemek için Aggregation Service API'yi kullanın.

• Adım 3.2.1. Toplu işlem için createJob uç noktası kullanılıyor
• Adım 3.2.2. Grup durumunu almak için getJob uç noktası kullanılıyor
• Adım 3.2.3. Özet Raporu İnceleme

3.1. Toplama Hizmeti Girişi Oluşturma

Toplama Hizmeti'nde toplu işlem yapmak 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 bu bağlantıya gidin; 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, "Rapor Gövdesi"nde de bulunur Chrome Dahili sayfasında görüntülenen raporların sayısı.

Burada çok sayıda rapor görebilirsiniz ancak bu codelab'de, GCP'ye özel ve hata ayıklama uç noktası tarafından oluşturulan toplanabilir raporu kullanın. "Rapor URL'si" "/debug/" ifadesini 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österilene benzer bir hata ayıklama raporu görmüyorsanız Özel Korumalı Alan demo sayfasını yenileyip Chrome dahili sayfasını yenileyin. Hata ayıklama uç noktası tarafından oluşturulan bir rapor da dahil olmak üzere daha fazla rapor göreceksiniz. Ayarlanmadıysa üçüncü taraf çerezlerinin etkin olup olmadığını bir kez daha kontrol edin.

3.1.2. Toplanabilir Raporları Toplama

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

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

Bu codelab'de rapor toplamayı manuel olarak gerçekleştiriyoruz. Üretimde, reklam teknolojilerinin raporları programatik olarak toplayıp dönüştürmesi beklenir.

Devam edelim ve "Rapor Gövdesi"ndeki JSON raporunu kopyalayalım. başlangıç fiyatı: chrome://private-aggregation-internals.

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

vim report.json

Raporu report.json alanına 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 dosyasının depolandığı yere gidin ve hata ayıklamayla ilgili toplanabilir rapor oluşturmaya yardımcı olması için aggregatable_report_converter.jar öğesini kullanın. Bu işlem, geçerli dizininizde report.avro adında toplanabilir bir rapor oluşturur.

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

3.1.4. Çıkış_alanı AVRO'su oluştur

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

Paket anahtarları adTech tarafından tasarlanmıştır. Ancak bu durumda, paket anahtarlarını Özel Korumalı Alan Demosu sitesi oluşturur. Bu site için gizli toplama hata ayıklama modunda olduğundan, "Rapor Gövdesindeki" debug_cleartext_payload öğesini kullanabiliriz. paket anahtarını alın.

Devam edin ve rapor gövdesinden debug_cleartext_payload değerini kopyalayın.

goo.gle/ags-payload-decoder adresini açın ve debug_cleartext_payload dosyanızı "INPUT" bölümüne yapıştırın kutusunu işaretleyin ve "Kodu Çö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.

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

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

Komut dosyası, geçerli klasörünüzde output_domain.avro dosyasını 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 taşımaya devam edin (Ön Koşul 1.6'da bunu belirttiğiniz).

Yerel ortamınızda gcloud KSA kurulumu varsa 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ı buraya yükleyin. "Çıkış_alanları" adlı bir klasör oluşturun ve output_domain.avro dosyasını buraya yükleyin.

3.2. Toplama Hizmeti Kullanımı

Önkoşul 1.8'de, Toplama Hizmeti uç noktalarına API istekleri yapmak için cURL veya Postman'i seçtiğinizi hatırlayın. Aşağıda her iki seçenekle ilgili talimatlar verilmiştir.

İşiniz bir hatayla başarısız olursa ne yapmanız gerektiği hakkında daha fazla bilgi edinmek için GitHub'daki sorun giderme dokümanlarımıza göz atın.

3.2.1. Toplu işlem için createJob uç noktası kullanılıyor

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

cURL

"Terminal"inizde bir istek gövde dosyası (body.json) oluşturun ve bunu aşağıya yapıştırın. Yer tutucu değerlerini güncellediğinizden emin olun. Her bir alanın neyi temsil ettiği hakkında daha fazla bilgi edinmek için bu API belgelerini inceleyin.

Not: Mümkünse attribution_report_to yerine job_parameters öğenizde tanımlanan reporting_site politikasını kullanmanızı öneririz. attribution_report_to alanının, Aggregation Service API arayüzünün bir sonraki ana sürüm yükseltmesinde desteğinin sonlandırıldığı tespit edildi. (Devamını okuyun) reporting_site parametresi, dağıtılan tek bir alan altında birden fazla kaynağa olanak tanırken, attribution_report_to parametresi 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. Diğer yandan, attribution_report_to için örnek değer https://dsp-a.example-dsp-host.com veya https://privacy-sandbox-demos-dsp.dev olabilir. Toplama Hizmeti'ne ilk katılım sırasında sağladığınız raporlama sitelerini unutmayın (Ön koşul 1.7). (Ö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ı, Ön Koşul 1.6'da Terraform dağıtımı başarıyla tamamlandıktan sonra verilen 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 edildikten sonra bir HTTP 202 yanıtı alırsınız. Diğer olası yanıt kodları API spesifikasyonlarında açıklanmıştır.

Postman

createJob uç noktası için, Toplama Hizmeti'ne toplanabilir raporların, çıkış alanlarının ve özet raporların konum ve dosya adlarını sağlamak amacıyla bir istek gövdesi gerekir.

createJob isteğinin "Gövde" bölümüne gidin sekmesinden:

Sağlanan JSON dosyasındaki yer tutucuları değiştirin. Bu alanlar ve bunların neleri temsil ettiği hakkında daha fazla bilgi için API dokümanlarına bakın.

Not: job_parameters öğenizde tanımlanan reporting_site yerine attribution_report_to öğesinin kullanılmasını önerin.

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

"Gönder" createJob API isteği:

Yanıt kodu sayfanın alt yarısında bulunabilir:

İstek, Toplama Hizmeti tarafından kabul edildikten sonra bir HTTP 202 yanıtı alırsınız. Diğer olası yanıt kodları API spesifikasyonlarında açıklanmıştır.

3.2.2. Grup durumunu almak için getJob uç noktası kullanılıyor

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

cURL

Aşağıdaki isteği Terminalinizde yürütün. URL'deki yer tutucuları, createJob isteği için kullandığınız URL'deki frontend_service_cloudfunction_url değerleriyle değiştirin. "job_request_id" için createJob uç noktasıyla oluşturduğunuz işteki değeri 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 HTTP durumu 200 ile döndürmelidir. "Gövde" isteği job_status, return_message ve error_messages (işte hata oluştuysa) gibi gerekli bilgileri içerir.

Not: Bu codelab için kullandığımız rapor, Özel Korumalı Alan demo sitesi raporlama kaynağıyla ilişkilendirilmiş. 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ım aşamasından farklı bir siteye ait olduğu için dönüş_kodunu 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. "Params" bölümünde bölümünde, job_request_id değerini createJob isteğinde gönderilen job_request_id olarak güncelleyin.getJob

"Gönder" getJob isteği:

Sonuç, iş isteğinizin durumunu HTTP durumu 200 ile döndürmelidir. "Gövde" isteği job_status, return_message ve error_messages (işte hata oluştuysa) gibi gerekli bilgileri içerir.

Not: Bu codelab için kullandığımız rapor, Özel Korumalı Alan demo sitesi raporlama kaynağıyla ilişkilendirilmiş. 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ım aşamasından farklı bir siteye ait olduğu için dönüş_kodunu PRIVACY_BUDGET_AUTHORIZATION_ERROR içeren bir yanıt alabilirsiniz. Bu beklenen bir durumdur ve yoksayılabilir.

3.2.3. Özet Raporu İnceleme

Özet raporunuzu çıkış Cloud Storage paketinize aldıktan sonra bunu 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 komutunu kullanabilirsiniz.

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

Bu, aşağıdakine benzer şekilde her paket anahtarının birleştirilmiş değerlerinin json dosyasını döndürür.

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

Raporda grup anahtarı, gürültüsüz metrik ve özet raporu oluşturmak için gürültüsüz metriğe eklenen gürültü yer alır. Rapor aşağıdakine benzer.

Ek açıklamalarda "in_reports" ibaresi de bulunur ve/veya "in_domain" Bunun anlamı şudur:

• in_reports: Paket anahtarı, toplanabilir raporların içinde bulunur.
• in_domain: Paket anahtarı, exit_domain AVRO dosyasının içinde yer alır.

Codelab tamamlandı.

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

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

4. 4. Temizleme

Toplama Hizmeti için oluşturulan kaynakları Terraform üzerinden silmek üzere adtech_setup ve dev (veya başka ortam) klasörlerinde bulunan yok etme 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ı barındıran Cloud Storage paketini silmek için:

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

Dilerseniz Chrome çerez ayarlarınızı Ön Koşul 1.2'den önceki durumuna geri döndürebilirsiniz.

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