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ş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/kullanma yok). Aggregation Service modu, Aggregation Service'in Google Cloud'da tam olarak dağıtılmasını gerektirir.

Bu codelab'i 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 işaretlenir.

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

Özel Korumalı Alan API'lerini kullanmak için hem Chrome hem de Android'de kayıt ve onay işlemlerini tamamladığınızı doğrulayın.

1.2. Reklam gizliliği API'lerini etkinleştirme (yerel test ve toplama hizmeti)

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

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

Ayrıca üçüncü taraf çerezlerinizin etkinleştirildiğini doğrulayın.

chrome://settings/cookies adresinde üçü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 çerezlerini engelle" = ETKİN

Çerezleri Etkinleştirme

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

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üklendiğini doğrulayın (Yerel Test ve Toplama Hizmeti)

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

Java sürümünü kontrol edin.

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

1.5. aggregatable_report_converter'ı indirin (Yerel Test ve Aggregation Service)

aggregatable_report_converter dosyasının bir kopyasını Özel Korumalı Alan Demoları GitHub deposundan indirebilirsiniz. GitHub deposunda IntelliJ veya Eclipse'in kullanılması gerektiği belirtiliyor ancak bu araçlar zorunlu değil. Bu araçları kullanmıyorsanız bunun yerine JAR dosyasını yerel ortamınıza indirin.

1.6. Cloud Platform ortamı oluşturma (toplama hizmeti)

Toplama hizmeti, bir bulut sağlayıcı kullanan güvenilir yürütme ortamının kullanılmasını gerektirir. Bu codelab'de, toplama hizmeti Google Cloud'da dağıtılacak ancak AWS de desteklenmektedir.

gcloud CLI'yı ayarlamak, Terraform ikililerini ve modüllerini indirmek ve Aggregation Service için Google Cloud kaynakları oluşturmak üzere GitHub'daki dağıtım talimatlarını uygulayın.

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

1. Ortamınızda "gcloud" komut satırı arayüzünü 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 bölümüne bakın. Burada oluşturulan veri paketi adını not edin. Bu ad, oluşturduğumuz dosyaları depolamak için codelab'de kullanılacaktır.
5. dev.auto.tfvars dosyasını güncelleyin, dağıtım hizmeti 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 bölümüne bakın.
6. Dağıtım tamamlandıktan sonra, sonraki adımlarda Toplama Hizmeti'ne istek göndermek için gerekli olan Terraform çıkışından frontend_service_cloudfunction_url değerini alın.

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

Aggregation Service'in kullanılabilmesi için koordinatörlerin hizmete dahil edilmesi 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 formunu doldurun. Bu hizmet hesabı, önceki ön koşulda (1.6. Google Cloud ortamı oluşturun). (İ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 haftayı bulabilir.

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

Bu codelab, Toplama Hizmeti API uç noktalarını çağırmak için 2 seçenek sunar: cURL ve Postman. cURL, minimum kurulum gerektirdiği ve ek yazılım içermediği için API uç noktalarını Terminalinizden çağırmanın daha hızlı ve kolay bir yoludur. Ancak cURL kullanmak istemiyorsanız bunun yerine Postman'i kullanarak API isteklerini yürütebilir ve ileride kullanmak üzere kaydedebilirsiniz.

Bölüm 3.2'de. Aggregation Service Kullanımı bölümünde, her iki seçeneğin de nasıl kullanılacağıyla ilgili ayrıntılı talimatlar yer alır. Hangi yöntemi kullanacağınızı belirlemek için bunları şimdi önizleyebilirsiniz. Postman'i seçerseniz aşağıdaki ilk kurulumu gerçekleştirin.

1.8.1. Çalışma alanı oluşturma

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

Postman çalışma alanı.

Sizin için bir çalışma alanı oluşturulmadıysa üst gezinme çubuğundaki "Çalışma alanları"na gidip "Çalışma alanı oluştur"u seçin.

"Boş çalışma alanı"nı seçin, sonraki seçeneğini tıklayın ve çalışma alanını "GCP Özel Korumalı Alan" olarak adlandırın. "Kişisel"i seçip "Oluştur"u tıklayın.

Önceden yapılandırılmış çalışma alanı JSON yapılandırmasını ve Global Environment dosyalarını indirin.

"İçe aktar" düğmesini kullanarak her iki JSON dosyasını da "Çalışma alanım"a aktarın.

İçe aktar düğmesi

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

1.8.2. Yetkilendirme kurulumu

"GCP Özel Korumalı Alan" koleksiyonunu tıklayın ve "Authorization" (Yetkilendirme) sekmesine gidin.

Yetkilendirme düğmesi.

"Bearer Token" 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:

"Jeton" alanı.

1.8.3. Ortamı ayarlama

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

Ortamın hızlı görünüm düğmesi.

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

Geçerli değerleri ayarlayın.

Daha sonra dolduracağımız için "request-id" alanını şimdilik boş bırakabilirsiniz. Diğer alanlar için, Ön Koşul 1.6'da Terraform dağıtımının başarılı bir şekilde tamamlanmasıyla 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 tamamlama süresi: 1 saatten kısa

Şifrelenmemiş hata ayıklama raporlarını kullanarak toplama işlemi gerçekleştirmek 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ızı doğrulayın.

Codelab adımları

Adım 2.1. Raporu tetikleme: Raporu toplayabilmek için Private Aggregation raporlamasını tetikleyin.

Adım 2.2. Hata Ayıklama AVRO Raporu Oluşturma: Toplanan JSON raporunu AVRO biçimli bir rapora dönüştürün. Bu adım, reklam teknolojileri API raporlama uç noktalarından raporları topladığında ve JSON raporlarını AVRO biçimli raporlara dönüştürdüğünde yapılan işleme benzer.

Adım 2.3. Paket anahtarlarını alma: Paket anahtarları, reklam teknolojisi şirketleri tarafından tasarlanır. Bu codelab'de paketler önceden tanımlandığı için paket anahtarlarını sağlandığı şekilde alın.

2.4. Adım: Çıkış alanı AVRO'su oluşturma: Bucket anahtarları alındıktan sonra çıkış alanı AVRO dosyasını oluşturun.

2.5. adım. Özet rapor oluşturma: Yerel ortamda özet raporlar oluşturabilmek için yerel test aracını kullanın.

Adım 2.6. Özet raporları inceleyin: Yerel Test Aracı tarafından oluşturulan özet raporu inceleyin.

2.1. Tetikleyici raporu

Private Aggregation 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 ve Onay ile Toplama Hizmeti'ne katılım işlemlerini tamamlamadıysanız Chrome flag'i ve CLI anahtarı kullanmanız gerekir.

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

Chrome Internals Page.

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

Burada birçok rapor görebilirsiniz ancak bu codelab için Google Cloud'a özel olan ve hata ayıklama uç noktası tarafından oluşturulan toplanabilir raporu kullanın. "Rapor URL'si" "/debug/" ifadesini, "Rapor Gövdesi"nin aggregation_coordinator_origin field bölümü ise https://publickeyservice.msmt.gcp.privacysandboxservices.com URL'sini içerir.

Google Cloud hata ayıklama raporu.

2.2. Hata Ayıklama Toplanabilir Raporu Oluşturma

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

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 içine yapıştırın ve dosyanızı kaydedin.

Raporun JSON kodu.

Bu bilgileri edindikten sonra, hata ayıklama için toplanabilir raporun oluşturulmasına yardımcı olması için aggregatable_report_converter.jar kullanın. Bu işlem, geçerli 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. Raporun Bucket Anahtarını Alma

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

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

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

Şifresiz metin ödeme yükünde hata ayıklayın.

goo.gle/ags-payload-decoder adresini açın, debug_cleartext_payload kodunuzu "INPUT" (GİRİŞ) kutusuna yapıştırıp "Decode" (Kod çöz) seçeneğini tıklayın.

Kod çözme düğmesi.

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

Örnek bir paket anahtarı.

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

Paket anahtarımız olduğuna göre, üzerinde çalıştığımız klasörde output_domain.avro oluşturalım. Bucket anahtarını, aldığınız bucket anahtarıyla değiştirdiğinizi doğrulayın.

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şturma

Aşağıdaki komutu kullanarak özet raporları oluşturmak için Ön Koşul 1.3'te 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 geçerli 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 ifade görürsünüz. Bu işlem tamamlandığında bir rapor output.avro oluşturulur.

Output AVRO

2.6. Özet raporu inceleme

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

AVRO raporunu tekrar 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 rapor output.json ile birlikte.

Çıkış JSON'u

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 rapor oluşturdunuz.

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

3. 3. Aggregation Service Codelab'i

Tahmini tamamlama süresi: 1 saat

Başlamadan önce, "Toplama Hizmeti" etiketli tüm ön koşulları tamamladığınızı doğrulayın.

Codelab adımları

3.1. adım: Toplama Hizmeti Girişi Oluşturma: Toplama Hizmeti için gruplandırılmış Toplama Hizmeti raporlarını oluşturun.

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

Adım 3.2. Toplama Hizmeti Kullanımı: Özet raporlar oluşturmak ve özet raporları incelemek için Toplama Hizmeti API'sini kullanın.

• Adım 3.2.1. createJob uç noktasını kullanarak toplu işleme
• Adım 3.2.2. Toplu durumunu almak için getJob uç noktasını kullanma
• 3.2.3.adım: Özet raporu inceleme

3.1. Aggregation Service Girişi Oluşturma

Toplama hizmetine toplu gönderme için AVRO raporları oluşturmaya devam edin. Bu adımlardaki kabuk komutları, Google Cloud'un Cloud Shell'inde (Ön Koşullar bölümündeki bağımlılıklar Cloud Shell ortamınıza kopyalandığı 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ı tıklayın. Ardından, raporları chrome://private-aggregation-internals adresinde görüntüleyebilirsiniz:

Chrome Internals Sayfası

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

Burada birçok rapor görebilirsiniz ancak bu codelab için Google Cloud'a özel olan ve hata ayıklama uç noktası tarafından oluşturulan toplanabilir raporu kullanın. "Rapor URL'si" "/debug/" ifadesini, "Rapor Gövdesi"nin aggregation_coordinator_origin field bölümü ise https://publickeyservice.msmt.gcp.privacysandboxservices.com URL'sini içerir.

Google Cloud hata ayıklama raporu.

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 Raporlama - Özet Rapor: {reporting-origin}/.well-known/attribution-reporting/report-aggregate-attribution

Bu codelab'de rapor koleksiyonu işlemini manuel olarak gerçekleştiriyoruz. Üretim aşamasında, reklam teknolojilerinin raporları programatik olarak toplaması ve dönüştürmesi beklenir.

chrome://private-aggregation-internals bölümündeki "Rapor Gövdesi"ndeki JSON raporunu kopyalayalım.

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 içine yapıştırın ve dosyanızı kaydedin.

Rapor JSON'u

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 öğesinin depolandığı yere gidin ve hata ayıklama için toplanabilir raporun oluşturulmasına yardımcı olması için aggregatable_report_converter.jar öğesini kullanın. Bu işlem, geçerli 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'sunu oluşturma

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

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

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

Şifresiz metin ödeme yükünde hata ayıklayın.

goo.gle/ags-payload-decoder adresini açın, debug_cleartext_payload kodunuzu "INPUT" (GİRİŞ) kutusuna yapıştırıp "Decode" (Kod çöz) seçeneğini tıklayın.

Kod çözme düğmesi.

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

Örnek bir paket anahtarı.

Paket anahtarımız olduğuna göre, üzerinde çalıştığımız klasörde output_domain.avro oluşturalım. Bucket anahtarını, aldığınız bucket anahtarıyla değiştirdiğinizi doğrulayın.

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 (Ön koşul 1.6'da belirttiğiniz) taşıyın.

Yerel ortamınızda gcloud CLI 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ı manuel olarak paketinize 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ı

Ön koşul 1.8'de, Toplama Hizmeti uç noktalarına API istekleri göndermek için curl veya Postman'i seçtiğinizi hatırlayın. Her iki seçenekle ilgili talimatlar aşağıda verilmiştir.

İş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ıza göz atın.

3.2.1. createJob uç noktasını kullanarak toplu işleme

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

curl

"Terminal"inizde bir istek gövdesi dosyası (body.json) oluşturun ve aşağıdaki JSON nesnesini 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ümanına bakın.

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
    "input_data_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
      "<report_folder>/<report_name-1>/",
      "<report_folder>/<report_name-2>/",
      "<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>", // Mutually exclusive to attribution_report_to 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 çıkışı yapılan 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 belgelenmiştir.

Postman

createJob uç noktası için, toplama hizmetine toplama yapılabilir raporların, çıkış alanlarının ve özet raporların konumunu ve dosya adlarını sağlamak üzere istek gövdesi gerekir.

createJob isteğinin "Body" (Gövde) sekmesine gidin:

Body sekmesi

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.

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/",
    "input_data_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
      "<report_folder>/<report_name-1>/",
      "<report_folder>/<report_name-2>/",
      "<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>", // Mutually exclusive to attribution_report_to as of v2.7.0
      "report_error_threshold_percentage": "10",
      "debug_run": "true"
    }
}

createJob API isteğini "Gönder"in:

Gönder düğmesi

Yanıt kodu, sayfanın alt yarısında yer alır:

Yanıt kodu

İ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 belgelenmiştir.

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

Bir iş almak için aşağıdaki curl veya Postman talimatlarından birini kullanın.

curl

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

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.

İş isteği kimliği

getJob isteğini "Gönder"in:

Gönder düğmesi

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

Yanıt JSON'u

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 tekrar JSON'a dönüştürülebilir. Bu komutu kullanarak raporunuzu okumak için aggregatable_report_converter.jar simgesini kullanabilirsiniz.

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

Bu işlem, her paket anahtarının aşağıdaki gibi görünen toplu değerlerinin bir JSON'unu döndürür.

Özet rapor.

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

Rapor; gruplandırma 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.

Gürültü raporu

Açıklamalarda "in_reports" veya "in_domain" (ya da her ikisi) de bulunur. Bunlar şu anlama gelir:

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

Codelab tamamlandı.

Özet: Toplama Hizmeti'ni kendi bulut ortamınıza dağıttınız, bir hata ayıklama raporu topladınız, bir çıkış alanı dosyası oluşturdunuz, bu dosyaları bir Cloud Storage paketinde sakladı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ımda yer alan temizleme talimatlarını uygulayarak az önce oluşturduğunuz bulut kaynaklarını silin.

4. 4. Temizleme

Terraform kullanarak Aggregation Service için oluşturulan kaynakları silmek üzere adtech_setup ve dev (veya başka bir ortam) klasörlerinde 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, Chrome çerez ayarlarınızı Ön Koşul 1.2'deki durumdan önceki durumuna 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:me@email.com"]

# 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 = "worker-sa@my-project-id.iam.gserviceaccount.com"

min_worker_instances = 1
max_worker_instances = 20