Firebase Admin SDK'yı sunucunuza ekleme

Yönetici SDK'si, aşağıdaki gibi işlemler gerçekleştirmek için ayrıcalıklı ortamlardan Firebase ile etkileşimde bulunmanıza olanak tanıyan bir dizi sunucu kitaplığıdır:

  • Tam yönetici ayrıcalıklarıyla Realtime Database verilerini okuma ve yazma.
  • Firebase Cloud Messaging sunucu protokollerine basit ve alternatif bir yaklaşım kullanarak Firebase Cloud Messaging mesajlarını programatik olarak gönderin.
  • Firebase kimlik doğrulama jetonları oluşturun ve doğrulayın.
  • Firebase projelerinizle ilişkili Cloud Storage paketleri ve Cloud Firestore veritabanları gibi Google Cloud kaynaklarına erişin.
  • Kullanıcı verilerini aramak veya kimlik doğrulama için bir kullanıcının e-posta adresini değiştirmek gibi işlemler yapmak üzere kendi basitleştirilmiş yönetici konsolunuzu oluşturun.

Node.js SDK'sını, son kullanıcı erişimi için istemci olarak (örneğin, Node.js masaüstü veya IoT uygulamasında) kullanmak istiyorsanız, ayrıcalıklı bir ortamdan (ör. sunucu) yönetici erişimi yerine, istemci JavaScript SDK'sını ayarlama talimatlarını uygulamanız gerekir.

Her dilde hangi Firebase özelliklerinin desteklendiğini gösteren bir özellik matrisi aşağıda verilmiştir:

Özellik Node.js Java Python Go C#
Özel Jeton Basma
Kimlik Jetonunu Doğrulama
Kullanıcı Yönetimi
Özel Hak Talepleriyle Erişimi Kontrol Etme
Jeton İptal Etmeyi Yenileme
Kullanıcıları İçe Aktarma
Oturum Çerezi Yönetimi
E-posta İşlemi Bağlantıları Oluşturma
SAML/OIDC sağlayıcı yapılandırmalarını yönetme
Çok kiracılı yapı desteği
Gerçek Zamanlı Veritabanı *
Firebase Cloud Messaging
FCM Çoklu Yayın
FCM Konu Aboneliklerini Yönetme
Cloud Storage
Cloud Firestore
Cloud Tasks ile işlevleri sıraya ekleme
Proje Yönetimi
Güvenlik Kuralları
Makine Öğrenimi Model Yönetimi
Firebase Uzaktan Yapılandırma
Firebase Uygulama Kontrolü
Firebase Extensions

Bu kullanımlar için Yönetici SDK'si entegrasyonu hakkında daha fazla bilgi edinmek istiyorsanız ilgili Realtime Database, FCM, Authentication, Remote Config ve Cloud Storage belgelerine bakın. Bu sayfanın geri kalanında, Admin SDK'nın temel kurulumuna odaklanılmıştır.

Ön koşullar

  • Sunucu uygulamanız olduğundan emin olun.

  • Kullandığınız Yönetici SDK'sına bağlı olarak sunucunuzun aşağıdakileri çalıştırdığından emin olun:

    • Yönetici Node.js SDK'sı - Node.js 14 ve sonraki sürümleri (Node.js 16 ve sonraki sürümleri önerilir)
      Node.js 14 desteği kullanımdan kaldırılmıştır.
    • Yönetici Java SDK'sı — Java 8+
    • Admin Python SDK'sı: Python 3.7+ (Python 3.8+ önerilir)
      Python 3.7 desteği kullanımdan kaldırılmıştır.
    • Admin Go SDK'sı - Go 1.20 ve sonraki sürümler
    • Yönetici .NET SDK'sı - .NET Framework 4.6.2 veya üzeri veya .NET 6.0 ve üzeri için .NET Standard 2.0

Firebase projesi ve hizmet hesabı oluşturun

Firebase Admin SDK'yı kullanmak için aşağıdakilere ihtiyacınız vardır:

  • Bir Firebase projesi.
  • Firebase ile iletişim kurmak için Firebase Admin SDK hizmet hesabı. Bu hizmet hesabı, Firebase projesi oluşturduğunuzda veya Firebase'i bir Google Cloud projesine eklediğinizde otomatik olarak oluşturulur.
  • Hizmet hesabınızın kimlik bilgilerini içeren bir yapılandırma dosyası.

Firebase projeniz yoksa Firebase konsolunda bir proje oluşturmanız gerekir. Firebase projeleri hakkında daha fazla bilgi edinmek için Firebase Projelerini Anlama sayfasını ziyaret edin.

SDK'yı ekle

Yeni bir proje oluşturuyorsanız seçtiğiniz dil için SDK'yı yüklemeniz gerekir.

Node.js

Firebase Admin Node.js SDK'sı npm'de kullanılabilir. package.json dosyanız yoksa npm init üzerinden bir dosya oluşturun. Ardından, firebase-admin npm paketini yükleyin ve package.json cihazınıza kaydedin:

npm install firebase-admin --save

Uygulamanızda kullanmak için modülü herhangi bir JavaScript dosyasından require:

const { initializeApp } = require('firebase-admin/app');

ES2015 kullanıyorsanız modülü import:

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

Java

Firebase Admin Java SDK'sı Maven merkezi deposunda yayınlanır. Kitaplığı yüklemek için build.gradle dosyanızda bağımlılık olarak tanımlayın:

dependencies {
  implementation 'com.google.firebase:firebase-admin:9.3.0'
}

Uygulamanızı derlemek için Maven'ı kullanıyorsanız pom.xml öğenize aşağıdaki bağımlılığı ekleyebilirsiniz:

<dependency>
  <groupId>com.google.firebase</groupId>
  <artifactId>firebase-admin</artifactId>
  <version>9.3.0</version>
</dependency>

Python

Firebase Admin Python SDK'sına pip üzerinden ulaşabilirsiniz. Kitaplığı tüm kullanıcılar için sudo aracılığıyla yükleyebilirsiniz:

sudo pip install firebase-admin

Alternatif olarak, --user işaretini ileterek kitaplığı yalnızca geçerli kullanıcı için yükleyebilirsiniz:

pip install --user firebase-admin

Go

Go Admin SDK, go get yardımcı programı kullanılarak yüklenebilir:

# Install the latest version:
go get firebase.google.com/go/v4@latest

# Or install a specific version:
go get firebase.google.com/go/v4@4.14.0

C#

.NET Yönetici SDK'sı, .NET paket yöneticisi kullanılarak yüklenebilir:

Install-Package FirebaseAdmin -Version 3.0.0

Alternatif olarak, dotnet komut satırı yardımcı programını kullanarak yükleyebilirsiniz:

dotnet add package FirebaseAdmin --version 3.0.0

Ya da .csproj dosyanıza aşağıdaki paket referansı girişini ekleyerek yükleyebilirsiniz:

<ItemGroup>
  <PackageReference Include="FirebaseAdmin" Version="3.0.0" />
</ItemGroup>

SDK'yı başlatma

Firebase projesi oluşturduktan sonra, SDK'yı Google Uygulaması Varsayılan Kimlik Bilgileri ile başlatabilirsiniz. Varsayılan kimlik bilgisi araması, Google ortamlarında tamamen otomatik hale getirildiğinden ve ortam değişkenleri veya başka yapılandırmalar sağlamaya gerek olmadığından Cloud Run, App Engine ve Cloud Functions gibi Google ortamlarında çalışan uygulamalar için SDK'yı bu şekilde başlatmanız önemle tavsiye edilir.

İsteğe bağlı olarak Realtime Database, Cloud Storage veya Cloud Functions gibi hizmetler için başlatma seçeneklerini belirtmek amacıyla FIREBASE_CONFIG ortam değişkenini kullanın. FIREBASE_CONFIG değişkeninin içeriği { ile başlıyorsa JSON nesnesi olarak ayrıştırılır. Aksi takdirde SDK, dizenin seçenekleri içeren bir JSON dosyasının yolu olduğunu varsayar.

Node.js

const app = initializeApp();

Java

FirebaseApp.initializeApp();

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create();

Başlatıldıktan sonra, aşağıdaki görev türlerini gerçekleştirmek için Admin SDK'yı kullanabilirsiniz:

OAuth 2.0 yenileme jetonu kullanma

Yönetici SDK'si, Google OAuth2 yenileme jetonuyla kimlik doğrulaması yapmanıza olanak tanıyan bir kimlik bilgisi de sağlar:

Node.js

const myRefreshToken = '...'; // Get refresh token from OAuth2 flow

initializeApp({
  credential: refreshToken(myRefreshToken),
  databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

Java

FileInputStream refreshToken = new FileInputStream("path/to/refreshToken.json");

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.fromStream(refreshToken))
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

cred = credentials.RefreshToken('path/to/refreshToken.json')
default_app = firebase_admin.initialize_app(cred)

Go

opt := option.WithCredentialsFile("path/to/refreshToken.json")
config := &firebase.Config{ProjectID: "my-project-id"}
app, err := firebase.NewApp(context.Background(), config, opt)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.FromFile("path/to/refreshToken.json"),
});

SDK'yı Google dışı ortamlarda başlatma

Varsayılan kimlik bilgisi arama işleminin tamamen otomatikleştirilemediği Google dışı sunucu ortamında çalışıyorsanız SDK'yı dışa aktarılmış bir hizmet hesabı anahtar dosyasıyla başlatabilirsiniz.

Firebase projeleri, uygulama sunucunuzdan veya güvenilir ortamınızdan Firebase sunucu API'lerini çağırmak için kullanabileceğiniz Google hizmet hesaplarını destekler. Yerel olarak kod geliştiriyorsanız veya uygulamanızı şirket içinde dağıtıyorsanız sunucu isteklerini yetkilendirmek için bu hizmet hesabından alınan kimlik bilgilerini kullanabilirsiniz.

Bir hizmet hesabının kimliğini doğrulamak ve Firebase hizmetlerine erişmesi için yetkilendirmek üzere JSON biçiminde bir özel anahtar dosyası oluşturmanız gerekir.

Hizmet hesabınıza ait özel anahtar dosyası oluşturmak için:

  1. Firebase konsolunda Ayarlar > Hizmet Hesapları'nı açın.

  2. Yeni Özel Anahtar Oluştur'u tıklayın, ardından Anahtar Oluştur'u tıklayarak işlemi onaylayın.

  3. Anahtarı içeren JSON dosyasını güvenli bir şekilde saklayın.

Bir hizmet hesabı aracılığıyla yetkilendirme yaparken, kimlik bilgilerini uygulamanıza sağlamak için iki seçeneğiniz vardır. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlayabilir veya yolu, kodda hizmet hesabı anahtarına açık bir şekilde aktarabilirsiniz. İlk seçenek daha güvenlidir ve kesinlikle önerilir.

Ortam değişkenini ayarlamak için:

GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini, hizmet hesabı anahtarınızı içeren JSON dosyasının dosya yoluna ayarlayın. Bu değişken yalnızca mevcut kabuk oturumunuz için geçerlidir. Bu nedenle, yeni bir oturum açarsanız değişkeni tekrar ayarlayın.

Linux veya macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

PowerShell ile:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Yukarıdaki adımları tamamlamanızın ardından Uygulama Varsayılan Kimlik Bilgileri (ADC) kimlik bilgilerinizi dolaylı olarak belirleyebilir. Bu sayede, Google dışı ortamlarda test ederken veya çalıştırırken hizmet hesabı kimlik bilgilerini kullanabilirsiniz.

SDK'yı aşağıdaki gibi başlatın:

Node.js

initializeApp({
    credential: applicationDefault(),
    databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
    ProjectId = "my-project-id",
});

Birden çok uygulamayı ilk kullanıma hazırlama

Çoğu durumda yalnızca tek bir varsayılan uygulamayı başlatmanız gerekir. Söz konusu uygulamanın dışındaki hizmetlere iki eşdeğer şekilde erişebilirsiniz:

Node.js

// Initialize the default app
const defaultApp = initializeApp(defaultAppConfig);

console.log(defaultApp.name);  // '[DEFAULT]'

// Retrieve services via the defaultApp variable...
let defaultAuth = getAuth(defaultApp);
let defaultDatabase = getDatabase(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = getAuth();
defaultDatabase = getDatabase();

Java

// Initialize the default app
FirebaseApp defaultApp = FirebaseApp.initializeApp(defaultOptions);

System.out.println(defaultApp.getName());  // "[DEFAULT]"

// Retrieve services by passing the defaultApp variable...
FirebaseAuth defaultAuth = FirebaseAuth.getInstance(defaultApp);
FirebaseDatabase defaultDatabase = FirebaseDatabase.getInstance(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = FirebaseAuth.getInstance();
defaultDatabase = FirebaseDatabase.getInstance();

Python

# Import the Firebase service
from firebase_admin import auth

# Initialize the default app
default_app = firebase_admin.initialize_app(cred)
print(default_app.name)  # "[DEFAULT]"

# Retrieve services via the auth package...
# auth.create_custom_token(...)

Go

// Initialize default app
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Access auth service from the default app
client, err := app.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

C#

// Initialize the default app
var defaultApp = FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});
Console.WriteLine(defaultApp.Name); // "[DEFAULT]"

// Retrieve services by passing the defaultApp variable...
var defaultAuth = FirebaseAuth.GetAuth(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = FirebaseAuth.DefaultInstance;

Bazı kullanım alanları, aynı anda birden fazla uygulama oluşturmanızı gerektirir. Örneğin, bir Firebase projesinin Realtime Database'inden veri okumak ve başka bir proje için özel jetonlar oluşturmak isteyebilirsiniz. Alternatif olarak, iki uygulamanın kimliğini ayrı kimlik bilgileriyle doğrulamak da isteyebilirsiniz. Firebase SDK'sı aynı anda her biri kendi yapılandırma bilgilerine sahip birden fazla uygulama oluşturmanıza olanak tanır.

Node.js

// Initialize the default app
initializeApp(defaultAppConfig);

// Initialize another app with a different config
var otherApp = initializeApp(otherAppConfig, 'other');

console.log(getApp().name);  // '[DEFAULT]'
console.log(otherApp.name);     // 'other'

// Use the shorthand notation to retrieve the default app's services
const defaultAuth = getAuth();
const defaultDatabase = getDatabase();

// Use the otherApp variable to retrieve the other app's services
const otherAuth = getAuth(otherApp);
const otherDatabase = getDatabase(otherApp);

Java

// Initialize the default app
FirebaseApp defaultApp = FirebaseApp.initializeApp(defaultOptions);

// Initialize another app with a different config
FirebaseApp otherApp = FirebaseApp.initializeApp(otherAppConfig, "other");

System.out.println(defaultApp.getName());  // "[DEFAULT]"
System.out.println(otherApp.getName());    // "other"

// Use the shorthand notation to retrieve the default app's services
FirebaseAuth defaultAuth = FirebaseAuth.getInstance();
FirebaseDatabase defaultDatabase = FirebaseDatabase.getInstance();

// Use the otherApp variable to retrieve the other app's services
FirebaseAuth otherAuth = FirebaseAuth.getInstance(otherApp);
FirebaseDatabase otherDatabase = FirebaseDatabase.getInstance(otherApp);

Python

# Initialize the default app
default_app = firebase_admin.initialize_app(cred)

#  Initialize another app with a different config
other_app = firebase_admin.initialize_app(cred, name='other')

print(default_app.name)    # "[DEFAULT]"
print(other_app.name)      # "other"

# Retrieve default services via the auth package...
# auth.create_custom_token(...)

# Use the `app` argument to retrieve the other app's services
# auth.create_custom_token(..., app=other_app)

Go

// Initialize the default app
defaultApp, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Initialize another app with a different config
opt := option.WithCredentialsFile("service-account-other.json")
otherApp, err := firebase.NewApp(context.Background(), nil, opt)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Access Auth service from default app
defaultClient, err := defaultApp.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

// Access auth service from other app
otherClient, err := otherApp.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

C#

// Initialize the default app
var defaultApp = FirebaseApp.Create(defaultOptions);

// Initialize another app with a different config
var otherApp = FirebaseApp.Create(otherAppConfig, "other");

Console.WriteLine(defaultApp.Name); // "[DEFAULT]"
Console.WriteLine(otherApp.Name); // "other"

// Use the shorthand notation to retrieve the default app's services
var defaultAuth = FirebaseAuth.DefaultInstance;

// Use the otherApp variable to retrieve the other app's services
var otherAuth = FirebaseAuth.GetAuth(otherApp);

Realtime Database ve Kimlik Doğrulama için kapsamları ayarla

Gerçek Zamanlı Veritabanı veya Kimlik Doğrulama için Google Uygulaması Varsayılan Kimlik Bilgilerine sahip bir Google Compute Engine sanal makinesi kullanıyorsanız doğru erişim kapsamlarını ayarladığınızdan emin olun. Realtime Database ve Authentication için userinfo.email ve cloud-platform ya da firebase.database ile biten kapsamlara ihtiyacınız vardır. Mevcut erişim kapsamlarını kontrol etmek ve değiştirmek için gcloud'u kullanarak aşağıdaki komutları çalıştırın.

gcloud

# Check the existing access scopes
gcloud compute instances describe [INSTANCE_NAME] --format json

# The above command returns the service account information. For example:
  "serviceAccounts": [
   {
    "email": "your.gserviceaccount.com",
    "scopes": [
     "https://www.googleapis.com/auth/cloud-platform",
     "https://www.googleapis.com/auth/userinfo.email"
     ]
    }
  ],

# Stop the VM, then run the following command, using the service account
# that gcloud returned when you checked the scopes.

gcloud compute instances set-service-account [INSTANCE_NAME] --service-account "your.gserviceaccount.com" --scopes "https://www.googleapis.com/auth/firebase.database,https://www.googleapis.com/auth/userinfo.email"

gcloud son kullanıcı kimlik bilgileriyle test etme

gcloud auth application-default login çalıştırılarak elde edilen Google Uygulaması Varsayılan Kimlik Bilgileri ile Yönetici SDK'sını yerel olarak test ederken, Firebase Authentication'ı kullanmak için aşağıdaki nedenlerden dolayı ek değişiklikler gerekir:

  • Firebase Authentication, gcloud OAuth istemci kimliği kullanılarak oluşturulan gcloud son kullanıcı kimlik bilgilerini kabul etmez.
  • Firebase Authentication, bu tür son kullanıcı kimlik bilgileri için başlatma sırasında proje kimliğinin sağlanmasını gerektirir.

Geçici bir çözüm olarak, kendi OAuth 2.0 istemci kimliğinizi kullanarak gcloud'da Google Uygulaması Varsayılan Kimlik Bilgileri oluşturabilirsiniz. OAuth istemci kimliği Masaüstü uygulaması uygulama türünde olmalıdır.

gcloud

gcloud auth application-default login --client-id-file=[/path/to/client/id/file]

Uygulama başlatılırken proje kimliğini açıkça belirtebilir veya yalnızca GOOGLE_CLOUD_PROJECT ortam değişkenini kullanabilirsiniz. İkinci yöntem, kodunuzu test etmek için ek değişiklikler yapma ihtiyacını ortadan kaldırır.

Proje kimliğini açıkça belirtmek için:

Node.js

import { initializeApp, applicationDefault } from 'firebase-admin/app';

initializeApp({
  credential: applicationDefault(),
  projectId: '<FIREBASE_PROJECT_ID>',
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setProjectId("<FIREBASE_PROJECT_ID>")
    .build();

FirebaseApp.initializeApp(options);

Python

app_options = {'projectId': '<FIREBASE_PROJECT_ID>'}
default_app = firebase_admin.initialize_app(options=app_options)

Go

config := &firebase.Config{ProjectID: "<FIREBASE_PROJECT_ID>"}
app, err := firebase.NewApp(context.Background(), config)
if err != nil {
        log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
    ProjectId = "<FIREBASE_PROJECT_ID>",
});

Sonraki adımlar

Firebase hakkında bilgi edinin:

Uygulamanıza Firebase özellikleri ekleyin: