このページは Cloud Translation API によって翻訳されました。

Data Connect で Admin SDK を使用する

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 は権限で動作するため、@auth ディレクティブを使用して設定されたアクセスレベル（NO_ACCESS レベルを含む）に関係なく、クエリとミューテーションを実行できます。

クライアントオペレーションと並行して、管理クエリとミューテーションを .gql ソースファイルに整理して管理スクリプトにインポートする場合は、認証アクセスレベルのない管理オペレーションをマークするか、より明示的に 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 には次の 2 つのインターフェースがあります。

ほとんどの読み取り / 書き込みオペレーションまたは読み取り専用オペレーション用の一般的なインターフェース。コードでクエリとミューテーションを実装し、読み取り / 書き込み 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 コンソールは、スキーマとコネクタの管理やサービスとデータベースの管理など、他のプロジェクト管理オペレーションに使用します。