Yönetici SDK'sını Data Connect ile kullanma

Firebase Admin SDK, ayrıcalıklı ortamlardan Firebase ile etkileşim kurmanıza olanak tanıyan bir dizi sunucu kitaplığıdır. Bu kitaplıklar, toplu veri yönetimi için Firebase Data Connect hizmetinde sorgu ve mutasyon gerçekleştirme gibi işlemlerin yanı sıra ayrıcalıklı kimlik bilgileri ve kimliğe bürünme ile diğer işlemleri yapmanıza olanak tanır.

Admin SDK, hem okuma/yazma hem de salt okuma modlarında işlemleri çağırmak için bir API sağlar. Salt okunur işlemler sayesinde, veritabanlarınızdaki verileri değiştiremeyen yönetim işlevlerini uygulayarak içiniz rahat bir şekilde çalışabilirsiniz.

Yönetici SDK'sını Kurulumu

Sunucunuzda Firebase Data Connect kullanmaya başlamak için öncelikle Node.js için Admin SDK'ı yükleyip ayarlamanız gerekir.

Admin SDK'yı komut dosyalarınızda başlatma

SDK'yı başlatmak için Data Connect uzantılarını içe aktarın ve proje hizmeti kimliğinizi ve konumunuzu bildirin.


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 ile kullanılacak sorgular ve mutasyonlar tasarlama

Aşağıdaki hususlar göz önünde bulundurulduğunda Admin SDK, Data Connect işlemlerini test etmek için kullanışlıdır.

SDK'yı ve @auth(level: NO_ACCESS) işlem yönergesini anlama

Admin SDK ayrıcalıklarla çalıştığından, NO_ACCESS düzeyi de dahil olmak üzere @auth yönergeleri kullanılarak ayarlanan erişim düzeylerinden bağımsız olarak sorgularınızın ve mutasyonlarınızın herhangi birini yürütebilir.

Müşteri işlemlerinizin yanı sıra yönetim sorgularınızı ve mutasyonlarınızı .gql kaynak dosyalarında düzenleyerek yönetim komut dosyalarına aktarıyorsanız Firebase, yetkilendirme erişim düzeyi olmayan yönetim işlemlerini işaretlemenizi veya daha açık bir şekilde NO_ACCESS olarak ayarlamanızı önerir. Her iki durumda da bu, söz konusu işlemlerin istemcilerden veya diğer ayrıcalıklı olmayan bağlamlarda yürütülmesini engeller.

SDK'yı Data Connect emülatörüyle kullanma

Prototip ve test ortamlarında, yerel veriler üzerinde veri doldurma ve diğer işlemleri yapmak faydalı olabilir. Admin SDK, yerel akışlarda kimlik doğrulama ve yetkilendirmeyi yoksaydığı için iş akışlarınızı basitleştirmenize olanak tanır.

Firebase Admin SDK'ları, Data Connect ortam değişkeni ayarlandığında otomatik olarak DATA_CONNECT_EMULATOR_HOST emülatörüne bağlanır:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

Daha fazla bilgi için aşağıdaki sayfaları inceleyin:

Yaygın kullanım alanlarını uygulama

Admin SDK, kritik verilerinizdeki ayrıcalıklı işlemler için sağlanır.

Admin SDK iki arayüz sağlar:

  • Çoğu okuma-yazma veya salt okunur işlem için genel bir arayüz. Bu arayüzde kodunuz sorguları ve mutasyonları uygular ve bunları okuma-yazma executeGraphql yöntemine veya salt okunur executeGraphqlRead yöntemine iletir.
  • Toplu veri işlemleri için özel bir arayüz. Bu arayüz, genel executeGraphql yöntemleri yerine mutasyon işlemleri için özel yöntemler sunar: insert, insertMany, upsert ve upsertMany.

executeGraphql yöntemleriyle kullanıcı verilerini yönetme

Admin SDK için tipik bir kullanım alanı, kullanıcı verilerini yönetmektir.

Yönetici kimlik bilgilerini kullanma

En basit yaklaşım, yönetici kimlik bilgilerini kullanarak kullanıcı verilerine erişmektir.

// 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" } } }

Kullanıcı kimlik bilgilerine bürünme

Ayrıca, komut dosyalarınızın belirli bir kullanıcı adına sınırlı kimlik bilgilerine göre kullanıcı verilerini değiştirmesini istediğiniz kullanım alanları da vardır. Bu yaklaşım, en az ayrıcalık ilkesine uygundur.

Bu arayüzü kullanmak için Authentication jeton biçimine uygun özelleştirilmiş bir JWT kimlik doğrulama jetonundan bilgi toplayın. Ayrıca özel jeton kılavuzuna da göz atın.

// 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" } } }

Herkese açık verileri executeGraphql yöntemleriyle yönetme

SDK'yı kullanarak herkese açık verilerle çalışabilir ve kimliği doğrulanmamış bir kullanıcının kimliğine bürünebilirsiniz.

// 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);

Toplu veri işlemleri gerçekleştirme

Firebase, üretim veritabanlarında toplu veri işlemleri için Admin SDK kullanılmasını önerir.

SDK, toplu verilerle çalışmak için aşağıdaki yöntemleri sağlar. Her yöntem, sağlanan bağımsız değişkenlerden bir GraphQL mutasyonu oluşturur ve yürütür.


// 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);

Toplu işlemlerle ilgili performans notları

Arka uca yapılan her istek, Cloud SQL'e bir gidiş-dönüş yolculuğu yapar. Bu nedenle, ne kadar çok toplu işlem yaparsanız işleme hızı o kadar yüksek olur.

Ancak toplu iş boyutu ne kadar büyük olursa oluşturulan SQL ifadesi de o kadar uzun olur. PostgreSQL SQL ifadesi uzunluk sınırına ulaşıldığında bir hatayla karşılaşırsınız.

Uygulamada, iş yükünüz için uygun toplu iş boyutunu bulmak üzere denemeler yapın.

Sırada ne var?