Firebase Admin SDK는 권한이 있는 환경에서 Firebase와 상호작용하여 권한이 상승되고 가장된 사용자 인증 정보로 일괄 데이터 관리 및 기타 작업을 위해 Firebase Data Connect 서비스에서 쿼리 및 변형을 실행하는 등의 작업을 수행할 수 있는 서버 라이브러리 집합입니다.
Admin SDK는 읽기/쓰기 모드와 읽기 전용 모드 모두에서 작업을 호출하는 API를 제공합니다. 읽기 전용 작업을 사용하면 데이터베이스의 데이터를 수정할 수 없는 관리 기능을 구현할 수 있어 안심할 수 있습니다.
Admin SDK 설정
서버에서 Firebase Data Connect를 사용하려면 먼저 Node.js용 Admin SDK를 설치하고 설정해야 합니다.
스크립트에서 Admin SDK 초기화
SDK를 초기화하려면 Data Connect 확장 프로그램을 가져오고 프로젝트 서비스 ID와 위치를 선언합니다.
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는 권한으로 작동하므로 NO_ACCESS
수준을 포함하여 @auth
지시어를 사용하여 설정된 액세스 수준과 관계없이 쿼리 및 변형을 실행할 수 있습니다.
클라이언트 작업과 함께 관리 쿼리 및 변형을 관리 스크립트로 가져오기 위해 .gql
소스 파일에 정리하는 경우 Firebase는 승인 액세스 수준 없이 관리 작업을 표시하거나 더 명시적으로 NO_ACCESS
로 설정할 것을 권장합니다. 어떤 경우든 이렇게 하면 클라이언트나 권한이 없는 다른 컨텍스트에서 이러한 작업이 실행되지 않습니다.
Data Connect 에뮬레이터와 함께 SDK 사용
프로토타입 및 테스트 환경에서는 로컬 데이터에 데이터 시딩 및 기타 작업을 실행하는 것이 유용할 수 있습니다. Admin SDK는 로컬 흐름의 인증 및 승인을 무시하므로 워크플로를 간소화할 수 있습니다.
DATA_CONNECT_EMULATOR_HOST
환경 변수가 설정되면 Firebase Admin SDK가 Data Connect 에뮬레이터에 자동으로 연결됩니다.
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" } } }
사용자 인증 정보 가장
또한 스크립트가 특정 사용자를 대신하여 제한된 사용자 인증 정보를 기반으로 사용자 데이터를 수정해야 하는 사용 사례도 있습니다. 이 접근 방식은 최소 권한의 원칙을 따릅니다.
이 인터페이스를 사용하려면 Authentication 토큰 형식을 따르는 맞춤 JWT 인증 토큰에서 정보를 수집하세요. 맞춤 토큰 가이드도 참고하세요.
// 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 문 길이 제한에 도달하면 오류가 발생합니다.
실제로 실험을 통해 워크로드에 적합한 배치 크기를 찾아보세요.
다음 단계
- Admin SDK를 사용하여 데이터로 데이터베이스를 시딩하는 방법 알아보기
- Admin SDK API를 검토합니다.
- Firebase CLI 및 Google Cloud 콘솔을 사용하여 스키마 및 커넥터 관리, 서비스 및 데이터베이스 관리와 같은 기타 프로젝트 관리 작업을 실행합니다.