Используйте Admin SDK с Data Connect

Firebase Admin SDK — это набор серверных библиотек, которые позволяют взаимодействовать с Firebase из привилегированных сред для выполнения таких действий, как выполнение запросов и мутаций в службе Firebase Data Connect для управления массовыми данными и других операций с повышенными привилегиями и олицетворенными учетными данными.

Admin SDK предоставляет вам API для вызова операций в режимах чтения/записи и только для чтения. С операциями только для чтения вы можете быть спокойны за реализацию административных функций, которые не могут изменять данные в ваших базах данных.

Настройка SDK администратора

Чтобы начать использовать Firebase Data Connect на своем сервере, вам сначала необходимо установить и настроить Admin SDK для Node.js.

Инициализируйте Admin SDK в своих скриптах

Чтобы инициализировать SDK, импортируйте расширения Data Connect и укажите идентификатор и местоположение службы вашего проекта.


import { initializeApp } from 'firebase-admin/app';
import { getDataConnect } from 'firebase-admin/data-connect';

// If you'd like to use OAuth2 flows and other credentials to log in,
// visit https://firebase.google.com/docs/admin/setup#initialize-sdk
// for alternative ways to initialize the SDK.

const app = initializeApp();

const dataConnect = getDataConnect({
    serviceId: 'serviceId',
    location: 'us-west2'
});

Разработка запросов и мутаций для использования с Admin SDK

Admin SDK полезен для тестирования операций Data Connect , учитывая следующие соображения.

Понимание SDK и директивы @auth(level: NO_ACCESS)

Поскольку Admin SDK работает с привилегиями, он может выполнять любые ваши запросы и мутации независимо от уровней доступа, установленных с помощью директив @auth , включая уровень NO_ACCESS .

Если наряду с клиентскими операциями вы организуете административные запросы и мутации в исходных файлах .gql для импорта в административные скрипты, Firebase рекомендует вам помечать административные операции без какого-либо уровня доступа авторизации или, возможно, быть более явным и устанавливать их как NO_ACCESS . В любом случае, это предотвращает выполнение таких операций с клиентов или в других непривилегированных контекстах.

Используйте SDK с эмулятором Data Connect

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

Firebase Admin SDK автоматически подключается к эмулятору Data Connect если задана переменная среды DATA_CONNECT_EMULATOR_HOST :

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

Более подробную информацию см. здесь:

Реализуйте общие варианты использования

Admin SDK предназначен для привилегированных операций с вашими критически важными данными.

Admin SDK предоставляет два интерфейса:

  • Общий интерфейс для большинства операций чтения-записи или только чтения, в котором ваш код реализует запросы и мутации и передает их методу чтения-записи executeGraphql или методу только чтения executeGraphqlRead .
  • Специализированный интерфейс для массовых операций с данными, который вместо общих методов executeGraphql предоставляет выделенные методы для операций мутации: insert , insertMany , upsert и upsertMany .

Управление данными пользователей с помощью методов executeGraphql

Типичным вариантом использования Admin SDK является управление пользовательскими данными.

Использовать административные учетные данные

Самый простой подход — получить доступ к данным пользователя с использованием административных учетных данных.

// User can be publicly accessible, or restricted to admins
const query = "query getProfile(id: AuthID) { user(id: $id) { id name } }";

interface UserData {
  user: {
    id: string;
    name: string;
  };
}

export interface UserVariables {
  id: string;
}

const options:GraphqlOptions<UserVariables> = { variables: { id: "QVBJcy5ndXJ1" } };

// executeGraphql
const gqlResponse = await dataConnect.executeGraphql<UserData, UserVariables>(query, options);

// executeGraphqlRead (similar to previous sample but only for read operations)
const gqlResponse = await dataConnect.executeGraphqlRead<UserData, UserVariables>(query, options);

// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }

Выдавать себя за учетные данные пользователя

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

Чтобы использовать этот интерфейс, соберите информацию из настроенного токена аутентификации JWT, который соответствует формату токена Authentication . Также см. руководство по пользовательским токенам .

// Get the current user's data
const queryGetUserImpersonation = `
    query getUser @auth(level: USER) {
        user(key: {uid_expr: "auth.uid"}) {
            id,
            name
        }
    }`;

// Impersonate a user with the specified auth claims
const optionsAuthenticated: GraphqlOptions<undefined> = {
    impersonate: {
        authClaims: {
            sub: 'QVBJcy5ndXJ1'
        }
    }
};

// executeGraphql with impersonated authenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetUserImpersonation, optionsAuthenticated);

// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }

Управление публичными данными с помощью методов executeGraphql

С помощью SDK вы можете работать с общедоступными данными, выдавая себя за неаутентифицированного пользователя.

// Query to get posts, with authentication level PUBLIC
const queryGetPostsImpersonation = `
    query getPosts @auth(level: PUBLIC) {
        posts {
          description
        }
    }`;

// Attempt to access data as an unauthenticated user
const optionsUnauthenticated: GraphqlOptions<undefined> = {
    impersonate: {
        unauthenticated: true
    }
};

// executeGraphql with impersonated unauthenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetPostsImpersonation, optionsUnauthenticated);

Выполнение массовых операций с данными

Firebase рекомендует использовать Admin SDK для массовых операций с данными в производственных базах данных.

SDK предоставляет следующие методы для работы с массивами данных. Из предоставленных аргументов каждый метод конструирует и выполняет мутацию GraphQL.


// Methods of the bulk operations API
// dc is a Data Connect admin instance from getDataConnect

const resp = await dc.insert("movie" /*table name*/, data[0]);
const resp = await dc.insertMany("movie" /*table name*/, data);
const resp = await dc.upsert("movie" /*table name*/, data[0]);
const resp = await dc.upsertMany("movie" /*table name*/, data);

Заметки о производительности для массовых операций

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

Однако чем больше размер пакета, тем длиннее генерируемый оператор SQL. Когда достигается предел длины оператора PostgreSQL SQL, вы столкнетесь с ошибкой.

На практике экспериментируйте, чтобы найти подходящий размер партии для вашей рабочей нагрузки.

Что дальше?