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. Özel Korumalı Alan API'lerini etkinleştir (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://flags/#privacy-sandbox-ads-apis adresine gidip Özel Korumalı Alan API'lerini etkinleştirin.

Özel Korumalı Alan API'lerini etkinleştirme

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

Tarayıcınızda chrome://settings/cookies adresine gidin. Üçü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ı 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.

Java sürümünü kontrol etme

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.

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.

1.6.1. Dağıtım

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.

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

  1. Ortamınızda "gcloud" CLI ve Terraform'u kurun.
  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.
  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.6.2. Rapor grubu

Proje kurulduktan sonra bu codelab'deki toplanabilir raporlarınızı ve özet raporlarınızı depolamak için Cloud Storage'da bir paket oluşturacaksınız. Bu, paket oluşturmaya yönelik örnek bir gcloud komutudur. Yer tutucuları istediğiniz bir ad ve konumla değiştirin.

gcloud storage buckets create gs://<bucket-name> --location=<location>

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, Toplama Hizmeti 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 API uç noktalarını Terminalinizden ç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.

Postacı Çalışma Alanı

Sizin için çalışma alanı oluşturulmadıysa "Çalışma alanları" ü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.

"İçe Aktar" düğmesini kullanarak her iki JSON dosyasını da "Çalışma Alanım" bölümüne 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 "Yetkilendirme" sekmesine gidin.

Yetkilendirme düğmesi

"Hamiline Ait Jeton" yöntemini kullanacaksınız. 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 Postman yetkilendirme sekmesinin "Token" (Jeton) alanına yapıştırın:

Jeton alanı

1.8.3. Ortamı ayarlama

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

Ortam düğmesi

"Düzenle"yi tıklayın ve "environment", "region" ve "cloud-function-id"nin "Geçerli Değeri"ni güncelleyin:

Geçerli değerleri ayarlayın

"request-id" alanını daha sonra dolduracağımız için şimdilik boş bırakabilirsiniz. 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 Kayıt ve Onay ile Toplama Hizmeti İlk Katılım işlemlerini tamamlamadıysanız Chrome flag'i ve CLI 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:

Chrome Dahili Sayfası

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

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, "Rapor Gövdesinin" aggregation_coordinator_origin field kısmında ise şu URL'yi içerir: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

GCP Hata Ayıklama Raporu

2.2. Hata Ayıklama Toplanabilir Raporu Oluştur

chrome://private-aggregation-internals ürününü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 (Ön Koşul 1.5'te indirilen depoda) 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 alanına yapıştırın ve dosyanızı kaydedin.

JSON bildirin

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, paket anahtarını almak için "Rapor Gövdesi"ndeki debug_cleartext_payload öğesini kullanabiliriz.

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

Hata Ayıklama (Cleartext Yükü)

goo.gle/ags-payload-decoder adresini açın ve debug_cleartext_payload dosyanızı "INPUT" kutusuna yapıştırdıktan sonra "Decode"u (Kodu Çöz) tıklayın.

Kodu çöz düğmesi

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

Paket anahtarı

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.

AVRO çıkışı

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.

JSON çıktısı

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:

Chrome Dahili Sayfası

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

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, "Rapor Gövdesinin" aggregation_coordinator_origin field kısmında ise şu URL'yi içerir: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

GCP Hata Ayıklama Raporu

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 chrome://private-aggregation-internals adresindeki "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 alanına yapıştırın ve dosyanızı kaydedin.

JSON bildirin

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, paket anahtarını almak için "Rapor Gövdesi"ndeki debug_cleartext_payload öğesini kullanabiliriz.

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

Hata Ayıklama (Cleartext Yükü)

goo.gle/ags-payload-decoder adresini açın ve debug_cleartext_payload dosyanızı "INPUT" kutusuna yapıştırdıktan sonra "Decode"u (Kodu Çöz) tıklayın.

Kodu çöz düğmesi

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

Paket anahtarı

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 son adım olarak oluşturduğunuz paket).

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ı bu klasöre 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.

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.

{
  "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>",
    "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.

Postacı

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" sekmesine gidin:

Gövde sekmesi

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.

{
  "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>",
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

createJob API isteğini "gönderin":

Gönder düğmesi

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

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

Postacı

İş 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 olarak güncelleyin.

İş isteği kimliği

getJob isteğini "gönderin":

Gönder düğmesi

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.

Yanıt JSON

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.

Özet rapor

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.

Gürültülü rapor

Ek açıklamalar ayrıca "in_reports" ve/veya "in_domain" değerlerini de içerir. Bu durum şu anlama gelir:

  • 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.

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: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