Data Clean Room: работа с источниками

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

• Дата и время:
  • Формат: гггг-МММ-дд чч:мм:сс (например, 2023-APR-18 15:30:35)
  • Часовой пояс: UTC
• Числа: до 2 символов после десятичного разделителя
• Длина строки: до 256 символов
• Ограничение по количеству символов:
  • Для имен полей (заголовки столбцов): без пробелов или специальных символов
  • Все прочие данные: без ограничений (все символы действительны)

В дополнение к данным, предоставляемым для обработки, таблицы источника в BigQuery или Snowflake должны содержать 2 дополнительных столбца: один для даты и один для версии:

• Дата:
  • Заголовок столбца: dt
  • Тип столбца: дата
  • Формат даты: гггг-мм-дд (например, 2023-04-18)
  • Дополнительно: Таблицы BigQuery должны быть разграничены по этому столбцу.
• Версия:
  • Заголовок столбца: v
  • Тип столбца: строка
  • Формат данных: число (например, 1, 2, 3, 10).
  • Важно! Новая версия отчета запускается каждый раз, когда DCR обнаруживает новое значение в этой колонке. Чтобы обеспечить полноту отчета, обязательно заполняйте таблицу источника полным набором данных при каждом изменении значения столбца.

Исходные файлы, хранящиеся в Amazon S3 или GCS, должны соответствовать этим требованиям к именам и форматам файлов:

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

1. Перейдите на вкладку Sources (Источники) в Data Clean Room.
2. Нажмите кнопку + New source (Создать источник).
   Откроется страница нового источника.
3. Введите имя источника в верхнем левом углу.
   • Им может быть любое уникальное имя, которое позволит вам идентифицировать этот источник на платформе DCR. Оно не обязательно должно совпадать с именем файла.
   • Важно! Убедитесь, что имя этого источника отличается от имен других источников в вашем аккаунте, иначе вы не сможете сохранить источник.
   • Требования к названию источника:
     • Длина: от 2 до 80 символов
     • Допустимые символы:
       • буквы (A–Z, a–z)
       • цифры (0-9), не могут быть первым символом имени; 
     • Недопустимые символы:
       • пробелы
       • все остальные символы или специальные символы

Чтобы указать расположение источника:

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

Расположение источника в BigQuery

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

1. Выберите набор данных, в котором находится таблица источника.
2. Выберите таблицу, в которой находятся исходные данные.

Списки, из которых вы делаете эти выборы, содержат доступные наборы данных и таблицы, соответственно, в проекте BigQuery, который вы указали при создании подключения.

Расположение источника в Snowflake

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

1. Выберите ресурс, содержащий исходные данные.
2. Выберите схему, в которой находится исходная таблица.
3. Выберите таблицу, в которой находятся исходные данные.

Списки, из которых вы делаете эти выборы, содержат общие ресурсы, схемы и таблицы, соответственно, в аккаунте Snowflake, который вы указали при создании подключения.

Расположение источника в облачных корзинах

Расположение источника в Amazon S3 или GCS состоит из облачной корзины, указанной при подключении, и пути к базовой папке, из которой DCR считывает исходный файл при каждом обновлении. 

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

• Позволив AppsFlyer генерировать папки, можно упростить процесс. Однако вместо этого вы можете создавать их вручную, следуя инструкциям, подробно описанным здесь.

Если AppsFlyer генерирует папки, единственная необходимая дополнительная информация — это имя, которое вы хотите дать папке источника. (Это папка верхнего уровня, в которой вы обновляете источник каждый раз, когда хотите использовать его для запуска новой версии отчета). Вы также можете указать, хотите ли вы, чтобы папка источника была создана под родительской папкой, часто называемой input.

Чтобы завершить указание расположения источника в облачной корзине, введите имя папки источника.

• По умолчанию отображенное имя папки источника:
  • Основано на имени, которое вы присвоили источнику. Вы можете изменить имя папки в соответствии со своими потребностями согласно требованиям к наименованиям DCR.
  • Указывает, что оно будет сгенерировано в родительской папке под именем input. Эта папка служит родительской папкой для всех источников, загруженных в DCR.
    • Папка input не является обязательной, и вы можете удалить ее или назвать ее по-другому в соответствии с требованиями к наименованиям DCR.
    • Хотя эта папка и не является обязательной, наличие папки input (или аналогичной папки с другим именем) считается правильным вариантом. Такой подход является еще более предпочтительным, если вы используете одну и ту же корзину и для загрузки файлов с данными (input), и для получения отчета (output).

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

• Загрузка исходных полей
• Отнесение каждого поля (колонки) к одному из следующих типов:
  • Identifier (Идентификатор). Поле, идентифицирующее уникального пользователя приложения (например, CUID, AppsFlyer ID и др.)
    • Основное назначение идентификаторов в контексте DCR — объединение источников данных для сопоставления соответствующих данных уровня пользователя.
  • Dimension (Параметр). Атрибут, по которому вы классифицируете пользователей приложения (например, гео, дата установки, кампания и др.)
  • Metric (Метрика). Числовые данные, собранные по пользователю приложения (например, доход, количество открытий приложения, LTV и др.)
    • Поле данных, отнесенное к категории метрик, может содержать только числовые значения.

Загрузка исходных полей

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

Источники в локальном хранилище данных

Чтобы загрузить поля из источника, расположенного в локальном хранилище данных (BigQuery или Snowflake), нажмите кнопку  .

Источники в облачных корзинах

Чтобы загрузить поля из источника, расположенного в облачном хранилище (Amazon S3 или GCS), необходимо загрузить файл прототипа источника.

Для определения структуры источника: 

• Можно загрузить макетную версию источника из локального файла.
  • Если вы выбираете эту опцию, AppsFlyer всегда автоматически использует путь папки источника.

                                                                - или -

• Можно загрузить версию-прототип источника прямо из его подключения.
  • Если вы выбираете эту опцию, есть дополнительный вариант:
    • Позволить AppsFlyer автоматически создать структуру папки источника; или
    • Создать структуру папки источника вручную

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

Определение категории полей

После загрузки полей AppsFlyer анализирует файл, и в списке Доступные поля отображается список всех полей данных (столбцы).

Чтобы определить категории полей:

1. Выберите одно или несколько полей в левой части списка Доступные поля и с помощью кнопок в центре экрана распределите их по категориям: идентификаторы, параметры или метрики.
   • Когда категория поля определена, оно отображается в списке соответствующей категории в правой части экрана.
   • Чтобы находить нужные поля в списках, можно использовать строку поиска.
   • Чтобы удалить поле из категории, к которой оно было отнесено, выберите его в соответствующем списке категорий и нажмите кнопку Удалить. Поле вернется в список Доступные поля.
2. Повторяйте этот процесс, пока не присвоите категории всем полям, которые требуется включить в отчеты DCR.
   • Классифицировать все поля в списке доступных полей не требуется. Если же поле будет использоваться в отчете, определять его категорию обязательно.
3. Если вы редактируете источник до сохранения источника и хотите использовать поля из отредактированных данных источника, перейдите по ссылке Перезагрузить поля в нижней части списка Доступные поля.
   • Обратите внимание, что при перезагрузке источника происходит перезапись имен полей в списке Доступные поля. Все поля, для которых вы ранее определили категории, останутся в списках Идентификаторы, Параметры или Метрики.
   • Если ранее классифицированного поля нет в повторно загруженных данных источника, оно будет отображаться в списке соответствующей категории со значком ошибки.

1. [Необязательно] Нажмите , чтобы проверить ошибки в формате или действительность полей источника.
2. Нажмите Save (Сохранить), чтобы сохранить источник.

   Источник создан, и на экране появляется сообщение с подтверждением.

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

   Новый источник отображается в списке всех имеющихся источников во вкладке Источники Data Clean Room.

Ниже приведена структура вложенных подпапок:

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

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

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

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

Имя файла для файла _SUCCESS:

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

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

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

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

Чтобы изменить имя источника:

1. Перейдите на вкладку Sources (Источники) в Data Clean Room.
2. В списке источников наведите курсор на строку с источником, который требуется отредактировать.
3. Нажмите кнопку «Редактировать» , которая отображается справа от строки.
4. На странице редактирования источника измените имя источника.
5. Нажмите кнопку Сохранить, чтобы сохранить источник под новым именем, или Отмена, чтобы отменить изменения.

Чтобы изменить структуру источника:

1. Перейдите на вкладку Sources (Источники) в Data Clean Room.
2. В списке источников наведите курсор на строку с источником, который требуется отредактировать.
3. Нажмите кнопку «Редактировать» , которая отображается справа от строки.
4. На странице редактирования источника поля, ранее классифицированные как идентификаторы, параметры и метрики, будут отображаться в списках соответствующих категорий в правой части экрана.
5. Вы можете перенести поле из одной категории в другую без повторной загрузки полей из файла источника. Для этого:
   1. Сначала выберите его в списке соответствующей категории и нажмите кнопку Remove (Удалить), чтобы оно вернулось в список доступных полей.
   2. Затем выберите его в списке доступных полей и с помощью кнопок в центре экрана определите его категорию: идентификатор, параметр или метрика.
6. Чтобы работать с полями из файла источника, не отнесенными к категориям, их нужно повторно загрузить из расположения источника или из локального файла. Сделайте этот выбор, нажав соответствующую ссылку Перезагрузить поля в нижней части списка Доступные поля.
7. AppsFlyer проанализирует файл, и все поля данных (столбцы) без категорий появятся в списке доступных полей.
   • Поля, уже классифицированные как идентификаторы, параметры и метрики, по прежнему будут отображаться в списках соответствующих категорий в правой части экрана.
   • Если ранее классифицированного поля нет в повторно загруженном файле источника, оно будет отображаться в списке соответствующей категории со значком ошибки.
8. Выберите одно или несколько полей в левой части списка Доступные поля и с помощью кнопок в центре экрана распределите их по категориям: идентификаторы, параметры или метрики.
9. Когда все необходимые изменения будут внесены, нажмите кнопку Сохранить, чтобы сохранить источник с обновленной структурой, или Отменить, чтобы сбросить внесенные изменения.

1. Перейдите на вкладку Sources (Источники) в Data Clean Room.
2. В списке источников наведите курсор на строку с источником, который вы хотите удалить.
3. Нажмите кнопку «Удалить» , которая отображается справа от строки.
4. В диалоговом окне подтвердите удаление источника.
   • Нельзя удалить источник, который используется в отчете. Если вы попробуете это сделать, в сообщении будет указан список отчетов, в которых задействован данный источник. Чтобы удалить такой источник, вы можете выполнить одно из следующих действий:
     • Удалить отчеты, в которых он используется.
     • Удалить поля источника из определений отчетов, в которых он используется.

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

Создайте папку для ключа DCR

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В каждой папке источника данных должны быть созданы вложенные подпапки по дате и версии при каждом обновлении источника.