Oluşturulan yönetici SDK'larını kullanma

Firebase SQL Connect Yönetici SDK'ları, sorgularınızı ve mutasyonlarınızı Cloud Functions, özel arka uçlar veya kendi iş istasyonunuz gibi güvenilir ortamlardan çağırmanıza olanak tanır. İstemci uygulamalarınız için SDK'lar oluşturmaya benzer şekilde, SQL Connect hizmetinize dağıttığınız şemaları, sorguları ve mutasyonları tasarlarken paralel olarak özel bir Admin SDK oluşturabilirsiniz. Ardından, bu SDK'daki yöntemleri arka uç mantığınıza veya yönetim komut dosyalarınıza entegre edersiniz.

Başka bir yerde de belirttiğimiz gibi, SQL Connect sorgularının ve mutasyonlarının istek sırasında istemciler tarafından gönderilmediğini unutmamak önemlidir. Bunun yerine, dağıtıldığında SQL Connect işlemleri Cloud Functions gibi sunucuda depolanır. Bu nedenle, sorgularınızda ve mutasyonlarınızda değişiklik yaptığınızda yönetici SDK'larını yeniden oluşturmanız ve bunlara bağlı tüm hizmetleri yeniden dağıtmanız gerekir.

Başlamadan önce

• SQL Connect şemaları, sorguları ve mutasyonları tasarlama hakkında bilgi edinin. Tipik bir iş akışında, bunları uygulamanızın koduyla paralel olarak geliştirirsiniz. Yönetici SDK'larını kullanan hizmetler de buna dahildir.

• Firebase CLI'yı yükleyin.

• Oluşturulan Admin SDK'larını çağırmayı planladığınız her yerde Node.js için Admin SDK'yı bağımlılık olarak ekleyin.

Yönetici SDK'ları oluşturma

SQL Connect şemalarınızı, sorgularınızı ve mutasyonlarınızı oluşturduktan sonra karşılık gelen bir Admin SDK oluşturabilirsiniz:

1. Bir connector.yaml dosyası açın veya oluşturun ve adminNodeSdk tanımı ekleyin:

   connectorId: default
   generate:
     adminNodeSdk:
       outputDir: ../../dataconnect-generated/admin-generated
       package: "@dataconnect/admin-generated"
       packageJsonDir: ../..
   

   connector.yaml dosyası genellikle sorgu ve değişiklik tanımlarınızı içeren GraphQL (.gql) dosyalarıyla aynı dizinde bulunur. İstemci SDK'larını daha önce oluşturduysanız bu dosya zaten oluşturulmuştur.

2. SDK'yı oluşturun.

   SQL Connect VS Code uzantısı yüklüyse oluşturulan SDK'lar her zaman güncel tutulur.

   Aksi takdirde Firebase CLI'yı kullanın:

   firebase dataconnect:sdk:generate

   Alternatif olarak, gql dosyalarınızı güncellediğinizde SDK'ların otomatik olarak yeniden oluşturulması için:

   firebase dataconnect:sdk:generate --watch

Yönetici SDK'sından işlemleri yürütme

Oluşturulan Admin SDK, gql tanımlarınıza karşılık gelen arayüzler ve işlevler içerir. Bunları, veritabanınızda işlemler gerçekleştirmek için kullanabilirsiniz. Örneğin, şarkı veritabanı için bir SDK oluşturduğunuzu ve sorgu eklediğinizi varsayalım: getSongs:

import { initializeApp } from "firebase-admin/app";
import { getSongs } from "@dataconnect/admin-generated";

const adminApp = initializeApp();

const songs = await getSongs(
  { limit: 4 },
  { impersonate: { unauthenticated: true } }
);

Alternatif olarak, bir konnektör yapılandırması belirtmek için:

import { initializeApp } from "firebase-admin/app";
import { getDataConnect } from "firebase-admin/data-connect";
import {
  connectorConfig,
  getSongs,
} from "@dataconnect/admin-generated";

const adminApp = initializeApp();
const adminDc = getDataConnect(connectorConfig);

const songs = await getSongs(
  adminDc,
  { limit: 4 },
  { impersonate: { unauthenticated: true } }
);

Kimliği doğrulanmamış bir kullanıcının kimliğine bürünme

Admin SDK'ları güvenilir ortamlarda çalıştırılmak üzere tasarlanmıştır ve bu nedenle veritabanlarınıza sınırsız erişime sahiptir.

Admin SDK ile herkese açık işlemler yaptığınızda, işlemi tam yönetici ayrıcalıklarıyla çalıştırmaktan kaçınmalısınız (en az ayrıcalık ilkesine uymak). Bunun yerine, işlemi kimliğine bürünülmüş bir kullanıcı (sonraki bölüme bakın) veya kimliğine bürünülmüş kimliği doğrulanmamış bir kullanıcı olarak çalıştırmanız gerekir. Kimliği doğrulanmamış kullanıcılar yalnızca PUBLIC olarak işaretlenen işlemleri çalıştırabilir.

Yukarıdaki örnekte, getSongs sorgusu kimliği doğrulanmamış bir kullanıcı olarak yürütülür.

Kullanıcının kimliğine bürünme

Ayrıca, Firebase Authentication jetonunun bir kısmını veya tamamını impersonate seçeneğine ileterek belirli kullanıcılar adına işlemler de gerçekleştirebilirsiniz. En azından, kullanıcının kullanıcı kimliğini sub talebinde belirtmeniz gerekir. (Bu, SQL Connect GraphQL işlemlerinde referans verebileceğiniz auth.uid sunucu değeri ile aynıdır.)

Bir kullanıcının kimliğine büründüğünüzde, sağladığınız kullanıcı verileri GraphQL tanımınızda belirtilen kimlik doğrulama kontrollerini geçerse işlem başarılı olur.

Oluşturulan SDK'yı herkese açık bir uç noktadan çağırıyorsanız uç noktanın kimlik doğrulama gerektirmesi ve kimlik doğrulama jetonunun bütünlüğünü, bir kullanıcının kimliğine bürünmek için kullanmadan önce doğrulamanız çok önemlidir.

Arama yapılabilir Cloud Functions kullanılırken kimlik doğrulama jetonu otomatik olarak doğrulanır ve aşağıdaki örnekte olduğu gibi kullanılabilir:

import { HttpsError, onCall } from "firebase-functions/https";

export const callableExample = onCall(async (req) => {
    const authClaims = req.auth?.token;
    if (!authClaims) {
        throw new HttpsError("unauthenticated", "Unauthorized");
    }

    const favoriteSongs = await getMyFavoriteSongs(
        undefined,
        { impersonate: { authClaims } }
    );

    // ...
});

Aksi takdirde, kimlik doğrulama jetonunu doğrulamak ve kodunu çözmek için Admin SDK'nın verifyIdToken yöntemini kullanın. Örneğin, uç noktanızın düz bir HTTP işlevi olarak uygulandığını ve standart olduğu gibi Firebase Authentication üst bilgisini kullanarak authorization jetonunu uç noktanıza ilettiğinizi varsayalım:

import { getAuth } from "firebase-admin/auth";
import { onRequest } from "firebase-functions/https";

const auth = getAuth();

export const httpExample = onRequest(async (req, res) => {
    const token = req.header("authorization")?.replace(/^bearer\s+/i, "");
    if (!token) {
        res.sendStatus(401);
        return;
    }
    let authClaims;
    try {
        authClaims = await auth.verifyIdToken(token);
    } catch {
        res.sendStatus(401);
        return;
    }

    const favoriteSongs = await getMyFavoriteSongs(
        undefined,
        { impersonate: { authClaims } }
    );

    // ...
});

Yalnızca güvenli ve herkese açık olmayan bir ortamda veri taşıma gibi gerçek idari görevleri gerçekleştirirken doğrulanabilir bir kaynaktan gelmeyen bir kullanıcı kimliği belirtmeniz gerekir:

// Never do this if end users can initiate execution of the code!
const favoriteSongs = await getMyFavoriteSongs(
  undefined,
  { impersonate: { authClaims } }
);

Sınırsız erişimle çalıştırma

Yönetici düzeyinde izinler gerektiren bir işlem yapıyorsanız çağrıdan kimliğe bürünme parametresini çıkarın:

await upsertSong(adminDc, {
  title: songTitle_one,
  instrumentsUsed: [Instrument.VOCAL],
});

Bu şekilde çağrılan bir işlem, veritabanına tam erişime sahiptir. Yalnızca yönetim amaçlarıyla kullanılmak üzere tasarlanmış sorgularınız veya mutasyonlarınız varsa bunları @auth(level: NO_ACCESS) yönergesiyle tanımlamanız gerekir. Bu işlem, yalnızca yönetici düzeyindeki arayanların bu işlemleri gerçekleştirebilmesini sağlar.