Data Clean Room: настройка облачного хранилища и файлов с данными

Краткий обзор. Настройте корзины в облачном сервисе, путь к папкам и файлы для AppsFlyer Data Clean Room. Корзины могут находиться в AWS S3, GCS или в обоих сервисах.

Обзор

С помощью AppsFlyer Data Clean Room (DCR) рекламодатели могут повысить ценность своих данных уровня пользователя, сопоставляя и дополняя их данными атрибуции уровня пользователя из AppsFlyer. В результате агрегированные отчеты обеспечивают конфиденциальность данных пользователей и предоставляют рекламодателям аналитические данные, доступные только в рамках такого комбинирования.

В рамках подготовки к использованию DCR требуется настроить хранилище в облачном сервисе и убедиться, что загружаемые вами файлы имеют нужный формат и корректно передаются в DCR.

Хранилище в облачном сервисе

Хранилище в облачном сервисе используется AppsFlyer Data Clean Room (DCR) для двух основных целей:

  • Входные данные: место, откуда AppsFlyer считывает данные, создаваемые вашей системой бизнес-аналитики.
  • Вывод: место, куда AppsFlyer доставляет отчеты после обработки DCR.

Для этих целей можно использовать одну или несколько корзин (в AWS, GCS или в обоих сервисах). При этом в большинстве случаев, самая простая в управлении структура выглядит следующим образом:

  • Одна корзина в одном облачном сервисе
  • Папка, определенная с помощью вашего ключа DCR непосредственно в корзине
  • Пути к двум отдельным папкам внутри папки верхнего уровня: одна для входных данных, другая — для вывода

В данной статье приведены инструкции по созданию такой структуры.

Требования DCR к именам

В отношении всех объектов данных в DCR (корзины, папки и файлы) действуют следующие требования к именованию:

  • Максимум 200 символов
  • Допустимые символы:
    • буквы (A–Z, a–z)
    • цифры (0–9), имя не может начинаться с цифры
    • дефисы (-), имя не может начинаться с дефиса
  • Недопустимые символы:
    • пробелы
    • все остальные символы или специальные символы
  • Символы, используемые только в определенных целях:

 Примечание

AWS и GCS автоматически добавляют косую черту (/) в конце названия папок. Не включайте этот символ в имена своих корзин или папок.

Создание корзины

Корзины создаются в интерфейсе выбранного вами облачного сервиса, как описано во вкладках ниже.

Следующие требования относятся к корзинам в обоих облачных сервисах:

  • Название хранилища:
    • Имя корзины должно начинаться с af-dcr-
    • Пример: af-dcr-example-bucket
  • Дополнительно:
    • Службе AppsFlyer DCR должны быть предоставлены права доступа к соответствующей корзине. Инструкции по предоставлению этих прав приведены на вкладках по каждому облачному сервису.
    • Корзина должна быть выделена исключительно для AppsFlyer Data Clean Room. Иными словами, никакие другие сервисы не могут записывать данные в эту корзину.

Корзина AWS

Примечание. Описанная ниже процедура должна быть выполнена вашим администратором AWS.

Чтобы создать корзину и предоставить разрешения AppsFlyer: 

  1. Войдите в консоль AWS.
  2. Откройте сервис S3.
  3. Чтобы создать корзину:
    1. Нажмите Создать корзину.
    2. Укажите имя в поле Bucket name (Название корзины): сначала префикс af-dcr-, затем ваш текст (как было описано выше).
    3. Нажмите Создать корзину.
  4. Чтобы предоставить AppsFlyer права доступа к корзине:
    1. Выберите созданную вами корзину. 
    2. Перейдите на вкладку Permissions (Разрешения). 
    3. В разделе Bucket policy (Политика корзины) нажмите Edit (Редактировать).
      Откроется окно для редактирования политики корзины.
    4. Вставьте в это окно следующий фрагмент кода.
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Sid": "AF-DCR",
            "Effect": "Allow",
            "Principal": {
              "AWS": "arn:aws:iam::195229424603:user/product=dcr-reporter__envtype=prod__ns=default"
            },
            "Action": [
              "s3:GetObject",
              "s3:ListBucket",
              "s3:DeleteObject",
              "s3:PutObject"
            ],
            "Resource": [
              "arn:aws:s3:::af-dcr-mybucket",
              "arn:aws:s3:::af-dcr-mybucket/*"
            ]
          }
        ]
      }
      
  5. Во фрагменте кода замените имя af-dcr-mybucket (в обеих строках, где оно встречается) на имя созданной вами корзины.
    Внимание! При замене имени корзины во фрагменте кода будьте внимательны, чтобы не удалить символы /* в строке, в которой имя корзины встречается второй раз.

  6. Нажмите Save changes (Сохранить изменения).

Корзина GCS

Примечание. Описанная ниже процедура должна быть выполнена вашим администратором Google Cloud.

Чтобы создать корзину и предоставить разрешения AppsFlyer: 

  1. Войдите в консоль GCS.
  2. Перейдите на страницу Cloud Storage Browser.
  3. Чтобы создать корзину:
    1. Нажмите  Create bucket (Создать корзину).
    2. Введите информацию о корзине на странице создания корзины . Укажите имя корзины: сначала префикс af-dcr-, затем ваш текст (как было описано выше).
    3. Нажмите Continue (Продолжить).
    4. Нажмите Create (Создать).
  4. Чтобы предоставить AppsFlyer права доступа к корзине:
    1. Выберите созданную вами корзину. 
    2. Перейдите на вкладку Permissions (Разрешения). 
    3. В разделе Permissions (Разрешения) нажмите + Add (Добавить).
      Откроется окно Add members (Добавить пользователей).
    4. В поле New members (Новые пользователи) вставьте следующий фрагмент кода.
      appsflyer-dcr@dcr-report.iam.gserviceaccount.com
    5. В списке Role (Роль) выберите Cloud storage (Облачное хранилище) > Storage Admin (Администратор хранилища).

      dcr_gcs_permissions.png

    6. Нажмите кнопку Save (Сохранить).

Создание папки для ключа DCR

Чтобы обеспечить максимальный уровень безопасности, имя папки, расположенной непосредственно в корзине («ключ DCR») должно содержать 8-значный буквенно-цифровой ключ DCR, присвоенный вашему аккаунту (например, 01bcc5fb). Обратите внимание, что он отличается от любого другого пароля или ключа, связанного с вашим аккаунтом AppsFlyer.

Папка с ключом DCR обычно создается вручную через интерфейс выбранного вами облачного сервиса.

Чтобы получить ключ DCR вашего аккаунта, нажмите кнопку «Ключ DCR» в верхней части главного экрана DCR.

dcr_key_button.png

 Пример

После создания папки с ключом DCR, структура корзины и папок будет выглядеть следующим образом:

af-dcr-example-bucket/01bcc5fb/

Создание пути к папке для входных данных

Требования к созданию каждого элемента пути папки для входных данных подробно описаны на вкладках ниже.

Папка верхнего уровня для входных данных

Хотя это не обязательно, рекомендуется создать папку верхнего уровня для входных данных непосредственно в папке с ключом DCR. Эта папка предназначена только для файлов, которые вы загружаете в DCR.

Папка верхнего уровня для входных данных обычно создается вручную через интерфейс выбранного вами облачного сервиса.

  • Такой подход является еще более предпочтительным, если вы используете одну корзину и для загрузки файлов с данными (входные данные), и для получения отчета (вывод).
  • Этой папке можно присвоить любое имя, соответствующее требованиям DCR к именам. Для удобства ее обычно называют input/.

 Пример

После создания папки верхнего уровня для входных данных структура корзины и папок будет выглядеть следующим образом:

af-dcr-example-bucket/01bcc5fb/input/

Папка второго уровня по каждому источнику данных

Вы можете регулярно загружать для обработки в DCR файлы с данными из различных источников. Каждому из таких источников данных должна быть назначена отдельная папка («папки источников данных»).

Например, если вы планируете ежедневно загружать на обработку в DCR два файла: BI-data.csv и CRM-data.gzip, каждому из этих источников данных нужно выделить папку. Соответствующие папки можно назвать, например, BI-data/ и CRM-data/.

Папки источников данных обычно создаются вручную через интерфейс выбранного вами облачного сервиса.

 Пример

После создания папок для двух источников данных структура корзины и папок будет выглядеть следующим образом:

af-dcr-example-bucket/01bcc5fb/input/BI-data/
                                     CRM-data/

Вложенные подпапки по датам и версиям

Мы наконец дошли до той части структуры папок, где все происходит, — до папок, непрерывно просматриваемых AppsFlyer на предмет новых файлов для чтения в DCR.

Каждый раз, когда вы хотите, чтобы AppsFlyer обработал файл источника данных и создал на его основе отчет, вам нужно загрузить новую версию этого файла в папку источника данных внутри серии вложенных подпапок, обозначающих дату и номер версии (плюс одна дополнительная подпапка, сообщающая AppsFlyer, где находятся данные):

  • В каждой папке источника данных --> 1 подпапка по каждой дате («папка даты»)
    • Формат: dt=гггг-мм-дд/
    • Пример: dt=2022-03-10/
  • В каждой папке даты --> 1 подпапка по каждой версии за эту дату («папка версии»)
    • Формат: v=n/
    • Пример: v=1/
    • Примечание. Папка версии требуется даже в том случае, если вы загружаете файл один раз в день.
  • В каждой папке версии --> 1 подпапка, указывающая расположение данных («папка с данными»)
    • Формат: data/

В большинстве случаев вы будете использовать вызовы API или другие доступные программные средства, чтобы папки даты/версии/данных создавались автоматически при каждой загрузке файла из источника данных. Дополнительную информацию см. в документации к API своего облачного сервиса: AWS, GCS.

Поскольку полная структура папок создается программно в момент загрузки файлов, реалистичный пример включает и файлы, и папки. См. иллюстрацию этого ниже на вкладке Файлы.

Файлы

Файлы из источников данных

Загружаемые файлы из источников данных должны отвечать следующим требованиям к имени, формату и расположению:

  • Должны соответствовать требованиям DCR к именам
  • Формат CSV или GZIP. Файл внутри архива GZIP должен иметь формат CSV.
  • Количество файлов из источников данных на папку с данными:
    • CSV: не более 1
    • GZIP: не более 1 цельного файла. Файлы GZIP из нескольких частей поддерживаются при условии следующего именования: имяфайла_part01.gzip, имяфайла_part02.gzip и т. д.

Данные в исходных файлах должны отвечать следующим требованиям:

  • Дата и время:
    • Формат: гггг-мм-дд чч:мм:сс
    • Часовой пояс: UTC
  • Числа: до 2 символов после десятичного разделителя
  • Длина строки: до 256 символов
  • Ограничения по символам: нет (все символы считаются допустимыми)

 

Файлы _SUCCESS

После загрузки файла источника данных в папку данных, в папку версии должен быть загружен пустой файл с именем _SUCCESS. Это сигнализирует AppsFlyer о том, что новый файл доступен для обработки. В большинстве случаев для автоматической загрузки этого файла используется скрипт API.

Важно! Файл _SUCCESS загружается в папку версии вне папки данных.

Имя файла:

  • ВСЕ ЗАГЛАВНЫЕ
  • Начинается с нижнего подчеркивания (_)
  • Не имеет расширения файла

Для файлов из нескольких частей:

  • Загружается только один файл _SUCCESS для всех частей файла.
  • Файл _SUCCESS должен загружаться только по завершении загрузки всех частей файла.

 Пример

После загрузки файлов источников данных за 2 дня (а также программного создания папок даты/версии/данных и файлов _SUCCESS) структура корзины и папок будет выглядеть следующим образом:

af-dcr-example-bucket/01bcc5fb/input/BI-data/
dt=2022-03-10/
v=1/
_SUCCESS
data/
BI-data.csv
dt=2022-03-11/
v=1/
_SUCCESS
data/
BI-data.csv CRM-data/
dt=2022-03-10/
v=1/
_SUCCESS
data/
CRM-data_part01.gzip
CRM-data_part02.gzip
v=2/
_SUCCESS
data/
CRM-data_part01.gzip
CRM-data_part02.gzip
dt=2022-03-11/
v=1/
_SUCCESS
data/
CRM-data_part01.gzip
CRM-data_part02.gzip
v=2/
_SUCCESS
data/
CRM-data_part01.gzip
CRM-data_part02.gzip

Создание пути к папке для вывода данных

Требования к созданию каждого элемента пути папки для вывода данных подробно описаны на вкладках ниже.

Папка верхнего уровня для вывода данных

Хотя это не обязательно, рекомендуется создать папку верхнего уровня для вывода данных непосредственно в папке с ключом DCR. Эта папка предназначена только для отчетов, предоставляемых DCR.

Папка верхнего уровня для вывода данных обычно создается вручную через интерфейс выбранного вами облачного сервиса.

  • Такой подход является еще более предпочтительным, если вы используете одну корзину и для загрузки файлов с данными (входные данные), и для получения отчета (вывод).
  • Этой папке можно присвоить любое имя, соответствующее требованиям DCR к именам. Для удобства ее обычно называют output/.

 Пример

После создания папки верхнего уровня для вывода данных структура корзины и папок будет выглядеть следующим образом:

af-dcr-example-bucket/01bcc5fb/output/

Папка второго уровня по каждому отчету

Вы можете регулярно получать из DCR любое количество отчетов с настраиваемой структурой. Каждому из таких отчетов должна быть назначена отдельная папка («папки отчетов»).

Например, если вы будете получать из DCR два отчета: отчет по конверсиям и отчет по ретаргетингу, каждому из этих источников данных нужно выделить папку. Соответствующие папки можно назвать, например, conversions/ и retargeting/.

Папки отчетов обычно создаются вручную через интерфейс выбранного вами облачного сервиса.

 Пример

После создания папок для двух отчетов структура корзины и папок будет выглядеть следующим образом:

af-dcr-example-bucket/01bcc5fb/output/conversions/
                                      retargeting/

Вложенные подпапки по датам и версиям (не создаются клиентом)

В отличие от пути к папке входных данных, вы не создаете вложенные папки дат/версий в пути папки для вывода данных. Эта структура папок автоматически создается AppsFlyer при каждой доставке отчета.

Формат файла отчета

Отчеты DCR предоставляются в формате CSV.

Была ли эта статья полезной?