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

Firebase Admin SDK, toplu veri yönetimi için bir Firebase Data Connect hizmetinde sorgu ve mutasyon çalıştırma gibi işlemleri ve ayrıcalıklı ayrıcalıklar ile kimliğe bürünmüş kimlik bilgileri kullanarak diğer işlemleri gerçekleştirmek üzere ayrıcalıklı ortamlardan Firebase ile etkileşim kurmanıza olanak tanıyan bir sunucu kitaplığı grubudur.

Admin SDK, işlemleri hem okuma/yazma hem de salt okuma modlarında çağırmanız 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 olabilir.

Yönetici SDK'sı Kurulumu

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

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

SDK'yı başlatmak için Data Connect uzantılarını içe aktarın ve projenizin hizmet kimliğini ve konumunu belirtin.


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

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

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

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

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

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

Prototip ve test ortamlarında, yerel verilerde veri ekleme ve diğer işlemleri gerçekleştirmek yararlı olabilir. Admin SDK, yerel akışlar için kimlik doğrulamayı ve yetkilendirmeyi yoksadığı için iş akışlarınızı basitleştirmenize olanak tanır.

DATA_CONNECT_EMULATOR_HOST ortam değişkeni ayarlandığında Firebase Admin SDK'ları otomatik olarak Data Connectemülatöre 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 verileriniz üzerinde ayrıcalıklı işlemler için sağlanır.

Yönetici SDK'sı iki arayüz sağlar:

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

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

Admin SDK'ün 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 bilgilerini taklit etme

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 uyar.

Bu arayüzü kullanmak için Authentication jeton biçimini izleyen özelleştirilmiş bir JWT kimlik jetonundan bilgi toplayın. Ö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 kullanmanızı ö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şlemler için performans notları

Arka uca yapılan her istek, Cloud SQL'e bir gidiş dönüş işlemi gerektirir. Bu nedenle, ne kadar çok toplu istek gönderirseniz işleme hızı o kadar yüksek olur.

Ancak toplu boyut ne kadar büyükse 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şlem boyutunu bulmak üzere deneme yapın.

Sırada ne var?