كيفية استخدام واجهة برمجة تطبيقات Supabase: دليل كامل

أصبح Supabase بسرعة بديلاً قويًا مفتوح المصدر لـ Firebase، حيث يوفر للمطورين مجموعة من الأدوات المبنية حول قاعدة بيانات PostgreSQL. في جوهره، يقدم Supabase طبقة API فورية في الوقت الحقيقي فوق قاعدة البيانات الخاصة بك، مما يسرع بشكل كبير تطوير الواجهة الخلفية. يوفر هذا الدليل لمحة شاملة حول كيفية الاستفادة من Supabase API، ويغطي كل شيء من الإعداد الأولي والعمليات الأساسية إلى الأمان والتخصيص والأمان من النوع.

1. المقدمة: ما هو Supabase API؟

على عكس تطوير الواجهة الخلفية التقليدي حيث قد تقضي وقتًا طويلاً في بناء نقاط نهاية REST أو GraphQL للتفاعل مع قاعدة البيانات الخاصة بك، يقوم Supabase تلقائيًا بإنشاء API آمن وفعال لك. عندما تنشئ جدولًا في قاعدة بيانات Supabase PostgreSQL الخاصة بك، يستخدم Supabase PostgREST، وهو أداة مفتوحة المصدر، لاستكشاف مخطط قاعدة البيانات الخاصة بك وتوفير نقاط نهاية RESTful المقابلة.

الفوائد الرئيسية:

• واجهة خلفية فورية: احصل على نقاط نهاية API وظيفية بمجرد تحديد مخطط قاعدة البيانات الخاصة بك.
• قدرات في الوقت الحقيقي: اشترك في تغييرات قاعدة البيانات عبر WebSockets.
• معتمد على PostgreSQL: الاستفادة من القوة والمرونة والنضج لـ PostgreSQL، بما في ذلك ميزات مثل أمان مستوى الصف (RLS).
• طرق تفاعل متعددة: التفاعل عبر REST أو GraphQL (مدعوم من المجتمع) أو مكتبات العميل الخاصة بـ Supabase (JavaScript وPython وDart وغيرها).
• قابلية التمدد: إنشاء وظائف مخصصة بدون خادم (Edge Functions) للمنطق المعقد أو التكاملات.

يركز هذا الدليل بشكل أساسي على REST API وتفاعله عبر مكتبات العميل، بالإضافة إلى وظائف Edge من Supabase.

2. البدء مع Supabase API

أسهل طريقة لفهم Supabase API هي البدء مباشرة. دعنا نفترض أنك قمت بإعداد مشروع Supabase (إذا لم يكن كذلك، قم بزيارة supabase.com وأنشئ واحدًا مجانًا) وقد أنشأت جدولًا بسيطًا، على سبيل المثال، profiles:

-- إنشاء جدول للملفات الشخصية العامة
create table profiles (
  id uuid references auth.users not null primary key,
  updated_at timestamp with time zone,
  username text unique,
  avatar_url text,
  website text,

  constraint username_length check (char_length(username) >= 3)
);

-- إعداد أمان مستوى الصف (RLS)
-- راجع https://supabase.com/docs/guides/auth/row-level-security لمزيد من التفاصيل.
alter table profiles
  enable row level security;

create policy "الملفات العامة قابلة للعرض من قبل الجميع." on profiles
  for select using (true);

create policy "يمكن للمستخدمين إدخال ملفهم الشخصي الخاص." on profiles
  for insert with check (auth.uid() = id);

create policy "يمكن للمستخدمين تحديث ملفهم الشخصي الخاص." on profiles
  for update using (auth.uid() = id);

-- يقوم هذا الزناد تلقائيًا بإنشاء إدخال ملف شخصي عندما يقوم مستخدم جديد بالتسجيل عبر Supabase Auth.
-- راجع https://supabase.com/docs/guides/auth/managing-user-data#using-triggers لمزيد من التفاصيل.
create function public.handle_new_user()
returns trigger as $$
begin
  insert into public.profiles (id, username)
  values (new.id, new.raw_user_meta_data->>'username');
  return new;
end;
$$ language plpgsql security definer;
create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_user();

(ملاحظة: المثال أعلاه يستخدم profiles، ويتماشى مع الأمثلة القياسية لـ Supabase. ينطبق المفهوم نفسه على جدول todos أو أي جدول آخر تقوم بإنشائه.)

البحث عن بيانات اعتماد API الخاصة بك:

يأتي كل مشروع Supabase مع بيانات اعتماد API فريدة:

1. رابط المشروع: نقطة النهاية الفريدة الخاصة بـ Supabase (على سبيل المثال، https://<your-project-ref>.supabase.co).
2. مفاتيح API: توجد في لوحة التحكم في مشروع Supabase الخاصة بك تحت إعدادات المشروع > API.

• anon (المفتاح العام): هذا المفتاح آمن للاستخدام في تطبيقات الجانب العملاء (مثل المتصفحات أو تطبيقات الهاتف المحمول). يعتمد على أمان مستوى الصف (RLS) للسيطرة على الوصول إلى البيانات.
• service_role (مفتاح الخدمة): هذا مفتاح سري يملك امتيازات إدارية كاملة، متجاوزًا RLS. لا تعرض هذا المفتاح في كود الجهة العميلة. استخدمه فقط في بيئات الخادم الآمنة (مثل الخوادم الخلفية أو وظائف بدون خادم).

التفاعل مع API (باستخدام مكتبة عميل Supabase JS):

يقدم Supabase مكتبات عميل لتبسيط التفاعلات مع API. إليك كيفية استخدام مكتبة JavaScript (supabase-js):

// 1. استيراد وتهيئة العميل
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = 'https://<your-project-ref>.supabase.co'
const supabaseAnonKey = '<your-anon-key>'

const supabase = createClient(supabaseUrl, supabaseAnonKey)

// 2. جلب البيانات (SELECT *)
async function getProfiles() {
  const { data, error } = await supabase
    .from('profiles')
    .select('*')

  if (error) console.error('خطأ في جلب الملفات الشخصية:', error)
  else console.log('الملفات الشخصية:', data)
}

// 3. إدخال البيانات (INSERT)
async function createProfile(userId, username) {
  const { data, error } = await supabase
    .from('profiles')
    .insert([
      { id: userId, username: username, updated_at: new Date() },
    ])
    .select() // إرجاع البيانات المدخلة

  if (error) console.error('خطأ في إنشاء الملف الشخصي:', error)
  else console.log('تم إنشاء الملف الشخصي:', data)
}

// 4. تحديث البيانات (UPDATE)
async function updateProfileUsername(userId, newUsername) {
  const { data, error } = await supabase
    .from('profiles')
    .update({ username: newUsername, updated_at: new Date() })
    .eq('id', userId) // تحديث فقط حيث تتطابق id
    .select()

  if (error) console.error('خطأ في تحديث الملف الشخصي:', error)
  else console.log('الملف الشخصي المحدث:', data)
}

// 5. حذف البيانات (DELETE)
async function deleteProfile(userId) {
  const { data, error } = await supabase
    .from('profiles')
    .delete()
    .eq('id', userId) // حذف فقط حيث تتطابق id

  if (error) console.error('خطأ في حذف الملف الشخصي:', error)
  // ملاحظة: غالبًا ما تعيد عملية الحذف بيانات محدودة عند النجاح ما لم تستخدم .select() *قبل* .delete() في بعض الإصدارات/الإعدادات.
  else console.log('تم حذف الملف الشخصي بنجاح')
}

// مثال للاستخدام (افترض أنك تملك ID مستخدم)
// getProfiles();
// createProfile('some-uuid-v4', 'new_user');
// updateProfileUsername('some-uuid-v4', 'updated_username');
// deleteProfile('some-uuid-v4');

تظهر هذه البداية السريعة العمليات الأساسية CRUD (إنشاء، قراءة، تحديث، حذف) باستخدام مكتبة العميل، والتي تتصل داخليًا بـ REST API.

3. Supabase REST API الذي تم إنشاؤه تلقائيًا

بينما توفر مكتبات العميل سهولة الاستخدام، فإن فهم REST API الأساسية التي يتم إنشاؤها بواسطة PostgREST أمر بالغ الأهمية.

هيكل نقاط نهاية API:

يكون رابط URL الأساسي لـ REST API عادةً: https://<your-project-ref>.supabase.co/rest/v1/

يتم إنشاؤها تلقائيًا نقاط النهاية لجدوالك:

• GET /rest/v1/your_table_name: يسترجع الصفوف من الجدول.
• POST /rest/v1/your_table_name: يضيف صفوف جديدة إلى الجدول.
• PATCH /rest/v1/your_table_name: يحدّث الصفوف الموجودة في الجدول.
• DELETE /rest/v1/your_table_name: يحذف الصفوف من الجدول.

المصادقة:

يجب أن تتضمن طلبات API مفتاح API الخاص بك في رأس apikey وعادةً رأس Authorization يحتوي على Bearer <your-api-key> (غالبًا ما يكون نفس مفتاح anon لطلبات الجانب العميل، أو مفتاح service_role لطلبات الجانب الخادم).

apikey: <your-anon-or-service-role-key>
Authorization: Bearer <your-anon-or-service-role-key>

العمليات الشائعة (باستخدام أمثلة curl):

دعنا نكرر الأمثلة السابقة باستخدام curl ضد REST API مباشرة. استبدل العناصر النائبة وفقًا لذلك.

جلب البيانات (GET):

curl 'https://<ref>.supabase.co/rest/v1/profiles?select=*' \
  -H "apikey: <anon-key>" \
  -H "Authorization: Bearer <anon-key>"

إدخال البيانات (POST):

curl 'https://<ref>.supabase.co/rest/v1/profiles' \
  -X POST \
  -H "apikey: <anon-key>" \
  -H "Authorization: Bearer <anon-key>" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \# اختياري: يعيد الصف المدخل \
  -d '{ "id": "some-uuid", "username": "rest_user" }'

تحديث البيانات (PATCH): (تحديث الملف الشخصي حيث يكون اسم المستخدم 'rest_user')

curl 'https://<ref>.supabase.co/rest/v1/profiles?username=eq.rest_user' \
  -X PATCH \
  -H "apikey: <anon-key>" \
  -H "Authorization: Bearer <anon-key>" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{ "website": "https://example.com" }'

حذف البيانات (DELETE): (احذف الملف الشخصي حيث يكون اسم المستخدم 'rest_user')

curl 'https://<ref>.supabase.co/rest/v1/profiles?username=eq.rest_user' \
  -X DELETE \
  -H "apikey: <anon-key>" \
  -H "Authorization: Bearer <anon-key>"

تصفية، اختيار، ترتيب، ترقيم:

يدعم REST API استعلامات قوية عبر معلمات URL:

• اختيار الأعمدة: ?select=column1,column2
• تصفية (التساوي): ?column_name=eq.value (على سبيل المثال، ?id=eq.some-uuid)
• تصفية (مشغلون آخرون): gt (أكبر من)، lt (أقل من)، gte، lte، neq (ليس متساويًا)، like، ilike (مشابه بدون اعتبار الحالة)، in (على سبيل المثال، ?status=in.(active,pending))
• الترتيب: ?order=column_name.asc أو ?order=column_name.desc (أضف .nullsfirst أو .nullslast إذا لزم الأمر)
• الترقيم: ?limit=10&offset=0 (احصل على أول 10)، ?limit=10&offset=10 (احصل على العشرة التالية)

وثائق API التي تم إنشاؤها تلقائيًا:

تعد واحدة من أكثر ميزات Supabase فائدة هي وثائق API التي يتم إنشاؤها تلقائيًا والتي تتوفر مباشرة داخل لوحة تحكم مشروعك.

1. انتقل إلى مشروع Supabase الخاص بك.
2. اضغط على أيقونة وثائق API (تبدو عادةً مثل <>) في الشريط الجانبي الأيسر.
3. اختر جدولاً تحت "الجداول وعروض البيانات".
4. سترى وثائق مفصلة لنقاط نهاية REST المحددة لذلك الجدول، بما في ذلك:

• طلبات أمثلة (Bash/curl، JavaScript).
• المرشحات المتاحة، والمحددات، والمعدلات.
• أوصاف للأعمدة وأنواع البيانات.

تعد هذه الوثائق التفاعلية ذات قيمة كبيرة لفهم كيفية هيكلة استدعاءات API الخاصة بك.

4. إنشاء أنواع لتعزيز التطوير باستخدام Supabase API

بالنسبة للمشاريع التي تستخدم TypeScript أو لغات ذات نوع آخر، يقدم Supabase وسيلة لإنشاء تعريفات النوع مباشرة من مخطط قاعدة البيانات الخاصة بك. يقدم ذلك فوائد كبيرة:

• أمان النوع: اكتشاف الأخطاء في وقت الترجمة بدلاً من وقت التشغيل.
• الإكمال التلقائي: الحصول على اقتراحات ذكية في محرر الأكواد الخاص بك لأسماء الجداول، وأسماء الأعمدة، ومعلمات الوظائف.
• تحسين القابلية للصيانة: تعتبر الأنواع بمثابة وثائق حية للهياكل البيانية الخاصة بك.

إنشاء أنواع باستخدام Supabase CLI:

1. تثبيت Supabase CLI: اتبع التعليمات في https://supabase.com/docs/guides/cli.
2. تسجيل الدخول: supabase login
3. رابط مشروعك: supabase link --project-ref <your-project-ref> (قم بتشغيل هذا في دليل المشروع المحلي الخاص بك). قد تحتاج إلى تقديم كلمة مرور قاعدة البيانات.
4. إنشاء الأنواع:

supabase gen types typescript --linked > src/database.types.ts
# أو حدد project-id إذا لم تكن مرتبطة أو في سياق مختلف
# supabase gen types typescript --project-id <your-project-ref> > src/database.types.ts

تقوم هذه الأوامر بفحص مخطط قاعدة البيانات لمشروع Supabase المرتبط الخاص بك وتخرج ملف TypeScript (database.types.ts في هذا المثال) يحتوي على واجهات لجداولك وعروض البيانات ومعلمات/أنواع عوائد الوظائف.

استخدام الأنواع التي تم إنشاؤها:

يمكنك بعد ذلك استيراد هذه الأنواع في كود تطبيقك:

import { createClient } from '@supabase/supabase-js'
// استيراد الأنواع التي تم إنشاؤها
import { Database } from './database.types' // تعديل المسار حسب الحاجة

const supabaseUrl = 'https://<your-project-ref>.supabase.co'
const supabaseAnonKey = '<your-anon-key>'

// توفير نوع قاعدة البيانات لإنشاء عميل
const supabase = createClient<Database>(supabaseUrl, supabaseAnonKey)

// الآن ستحصل على أمان النوع والإكمال التلقائي!
async function getSpecificUserProfile(username: string) {
  // الإكمال التلقائي لأسماء الجداول ('profiles')
  const { data, error } = await supabase
    .from('profiles')
    // الإكمال التلقائي لأسماء الأعمدة ('id'، 'username'، 'website')
    .select('id, username, website')
    // تحقق من النوع للقيمة بالنسبة لنوع العمود
    .eq('username', username)
    .single() // يتوقع نتيجة واحدة أو null

  if (error) {
    console.error('خطأ في جلب الملف الشخصي:', error)
    return null;
  }

  // 'data' الآن مُحددة بشكل صحيح بناءً على استعلام الاختيار الخاص بك
  if (data) {
    console.log(`معرف المستخدم: ${data.id}, الموقع الإلكتروني: ${data.website}`);
    // console.log(data.non_existent_column); // <-- خطأ TypeScript!
  }

  return data;
}

إن إنشاء الأنواع هو ممارسة موصى بها بشدة لتطوير التطبيقات بشكل موثوق مع Supabase.

5. إنشاء مسارات Supabase API مخصصة باستخدام وظائف Edge

بينما يغطي REST API الذي تم إنشاؤه تلقائيًا عمليات CRUD القياسية، ستحتاج غالبًا إلى منطق مخصص على الخادم لـ:

• التكامل مع خدمات الطرف الثالث (مثل Stripe وTwilio).
• إجراء حسابات معقدة أو تجميع البيانات.
• تشغيل منطق يتطلب امتيازات مرتفعة (service_role key) دون تعريض المفتاح للجهة العميلة.
• فرض قواعد العمل المعقدة.

توفر وظائف Supabase Edge Functions وسيلة لنشر وظائف TypeScript المعتمدة على Deno عالميًا على الحافة، بالقرب من المستخدمين.

إنشاء وظيفة Edge:

1. تهيئة الوظائف (إذا لم تكن قد قمت بذلك بالفعل): supabase functions new hello-world (قم بالتشغيل في دليل مشروعك المرتبط). هذا ينشئ ملفًا supabase/functions/hello-world/index.ts.

اكتب كود الوظيفة الخاصة بك:

// supabase/functions/hello-world/index.ts
import { serve } from 'https://deno.land/std@0.177.0/http/server.ts' // استخدم الإصدار المناسب من std

serve(async (req) => {
  // يمكنك الوصول إلى رؤوس الطلبات، والطريقة، والجسم وما إلى ذلك. من 'req'
  console.log(`تم استلام الطلب من أجل: ${req.url}`);

  // مثال: الوصول إلى قاعدة بيانات Supabase من داخل الوظيفة
  // ملاحظة: يتطلب إعداد عميل Supabase *داخل* الوظيفة
  // استخدم متغيرات البيئة من أجل الأسرار!
  // import { createClient } from '@supabase/supabase-js'
  // const supabaseAdmin = createClient(
  //   Deno.env.get('SUPABASE_URL') ?? '',
  //   Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
  // )
  // const { data: users, error } = await supabaseAdmin.from('profiles').select('*').limit(10);

  const data = {
    message: `مرحبا من Edge!`,
    // users: users // مثال إذا كنت تقوم بجلب البيانات
  }

  return new Response(
    JSON.stringify(data),
    { headers: { 'Content-Type': 'application/json' } },
  )
})

نشر الوظيفة:

supabase functions deploy hello-world --no-verify-jwt
# استخدم --no-verify-jwt للوظائف المتاحة بشكل عام
# اتركه أو اضبط --verify-jwt=true لتتطلب JWT صلاحية Supabase

استدعاء الوظيفة:
يمكنك استدعاء الوظائف المنشورة عبر طلبات HTTP POST (أو GET، حسب منطق الوظيفة) إلى نقطة النهاية الفريدة الخاصة بهم:
https://<your-project-ref>.supabase.co/functions/v1/hello-world

باستخدام curl:

curl -X POST 'https://<ref>.supabase.co/functions/v1/hello-world' \
  -H "Authorization: Bearer <user-jwt-if-required>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Functions"}' # جسم الطلب الاختياري

أو باستخدام عميل Supabase JS:

const { data, error } = await supabase.functions.invoke('hello-world', {
  method: 'POST', // أو 'GET'، إلخ.
  body: { name: 'Functions' }
})

تعد وظائف Edge أداة قوية لتوسيع قدرات خلفية Supabase إلى ما هو أبعد من عمليات قاعدة البيانات البسيطة.

6. مفاتيح API وتأمين Supabase API الخاص بك

فهم مفاتيح API وتنفيذ تدابير الأمان المناسبة أمر لا يمكن التفاوض عليه.

تكرار مفاتيح API:

• anon (المفتاح العام): للاستخدام على جانب العميل. يعتمد بالكامل على أمان مستوى الصف (RLS) لحماية البيانات.
• service_role (مفتاح الخدمة): للاستخدام على جانب الخادم فقط. يتجاوز RLS، مما يمنح الوصول الكامل إلى قاعدة البيانات. احرص على حماية هذا المفتاح بعناية.

الدور الحيوي لأمان مستوى الصف (RLS):

RLS هو حجر الزاوية لأمان Supabase عند استخدام المفتاح anon. يسمح لك بتعريف سياسات التحكم في الوصول الدقيقة مباشرة داخل قاعدة بيانات PostgreSQL. تعتبر السياسات ببساطة قواعد SQL تحدد الصفوف التي يمكن للمستخدم عرضها أو إدراجها أو تحديثها أو حذفها بناءً على حالته المصرح بها، أو معرف المستخدم، أو دوره، أو معايير أخرى.

تمكين RLS:

بشكل افتراضي، يكون RLS معطلاً على الجداول الجديدة. يجب عليك تمكينه لأي جدول تنوي الوصول إليه من جانب العميل باستخدام مفتاح anon.

-- تمكين RLS على جدول 'profiles'
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

-- هام: إذا لم يتم تعريف أي سياسات بعد تمكين RLS،
-- يتم رفض الوصول بشكل ضمني لجميع العمليات (باستثناء مالك الجدول).

إنشاء سياسات RLS:

تحدد السياسات فقرة USING (للوصول للقراءة مثل SELECT وUPDATE وDELETE) وفقرة WITH CHECK (للوصول للكتابة مثل INSERT وUPDATE).

المثال 1: السماح للمستخدمين المسجلين بقراءة جميع الملفات الشخصية:

CREATE POLICY "السماح بالوصول المصرح به للقراءة"
ON profiles FOR SELECT
USING ( auth.role() = 'authenticated' );

المثال 2: السماح للمستخدمين بعرض ملفهم الشخصي فقط:

CREATE POLICY "السماح بالوصول الفردي للقراءة"
ON profiles FOR SELECT
USING ( auth.uid() = id ); -- يفترض مطابقة عمود 'id' مع UUID المستخدم من Supabase Auth

المثال 3: السماح للمستخدمين بتحديث ملفهم الشخصي فقط:

CREATE POLICY "السماح بالوصول الفردي للتحديث"
ON profiles FOR UPDATE
USING ( auth.uid() = id ) -- يحدد الصفوف التي يمكن استهدافها للتحديث
WITH CHECK ( auth.uid() = id ); -- يضمن أن أي بيانات *جديدة* لا تزال تتطابق مع الشرط

المثال 4: السماح للمستخدمين بإدخال ملفهم الشخصي:

CREATE POLICY "السماح بالوصول الفردي للإدراج"
ON profiles FOR INSERT
WITH CHECK ( auth.uid() = id );

يمكنك عرض وإنشاء وإدارة سياسات RLS مباشرة في لوحة تحكم Supabase تحت المصادقة > السياسات.

مبادئ الأمان الرئيسية:

1. قم دائمًا بتمكين RLS على الجداول التي يتم الوصول إليها عبر مفتاح anon.
2. حدد سياسات واضحة لـ SELECT وINSERT وUPDATE وDELETE حسب الحاجة. ابدأ بسياسات صارمة وافتح الوصول بحذر.
3. لا تعرض مطلقًا service_role المفتاح في كود الجانب العميل أو في البيئات غير الآمنة.
4. استخدم وظائف Edge لعمليات تتطلب امتيازات مرتفعة أو منطق معقد على الخادم، مع حماية مفتاح service_role داخل المتغيرات البيئية الآمنة للوظيفة.
5. راجع بانتظام سياسات RLS الخاصة بك لضمان أنها تلبي متطلبات الأمان لتطبيقك.

7. رسم مفاهيم SQL إلى Supabase API (SQL إلى API)

إذا كنت معتادًا على SQL، فإن فهم كيفية رسم العمليات الشائعة في SQL إلى Supabase API (كلا من REST ومكتبات العميل) يساعد.

SELECT * FROM my_table;

• REST: GET /rest/v1/my_table?select=*
• JS: supabase.from('my_table').select('*')

SELECT column1, column2 FROM my_table WHERE id = 1;

• REST: GET /rest/v1/my_table?select=column1,column2&id=eq.1
• JS: supabase.from('my_table').select('column1, column2').eq('id', 1)

INSERT INTO my_table (column1, column2) VALUES ('value1', 'value2');

• REST: POST /rest/v1/my_table مع جسم JSON {"column1": "value1", "column2": "value2"}
• JS: supabase.from('my_table').insert({ column1: 'value1', column2: 'value2' })

UPDATE my_table SET column1 = 'new_value' WHERE id = 1;

• REST: PATCH /rest/v1/my_table?id=eq.1 مع جسم JSON {"column1": "new_value"}
• JS: supabase.from('my_table').update({ column1: 'new_value' }).eq('id', 1)

DELETE FROM my_table WHERE id = 1;

• REST: DELETE /rest/v1/my_table?id=eq.1
• JS: supabase.from('my_table').delete().eq('id', 1)

التوصيلات: بينما لا تستخدم بناء جملة SQL JOIN المباشر في المكالمات REST الأساسية، يمكنك جلب البيانات ذات الصلة باستخدام:

• علاقات المفتاح الخارجي: ?select=*,related_table(*) يجلب البيانات من الجداول ذات الصلة المعرفة بواسطة المفاتيح الخارجية.
• JS: supabase.from('my_table').select('*, related_table(*)')
• RPC (استدعاءات الإجراءات البعيدة): للحصول على وصلات معقدة أو منطق، أنشئ وظيفة PostgreSQL واستدعها عبر API.

-- مثال على وظيفة SQL
CREATE FUNCTION get_user_posts(user_id uuid)
RETURNS TABLE (post_id int, post_content text) AS $$
  SELECT posts.id, posts.content
  FROM posts
  WHERE posts.author_id = user_id;
$$ LANGUAGE sql;

• REST: POST /rest/v1/rpc/get_user_posts مع جسم JSON {"user_id": "some-uuid"}
• JS: supabase.rpc('get_user_posts', { user_id: 'some-uuid' })

8. استخدام المخططات المخصصة مع Supabase API

بشكل افتراضي، الجداول التي تقوم بإنشائها في محرر SQL الخاص بـ Supabase تقع في مخطط public. من أجل تنظيم أفضل، أو إدارة الأسماء، أو إدارة الأذونات، قد ترغب في استخدام مخططات PostgreSQL مخصصة.

إنشاء مخطط مخصص:

CREATE SCHEMA private_schema;

إنشاء جداول في مخطط مخصص:

CREATE TABLE private_schema.sensitive_data (
  id serial primary key,
  payload jsonb
);

الوصول إلى الجداول في المخططات المخصصة عبر API:

تكتشف طبقة PostgREST في Supabase تلقائيًا الجداول في المخططات التي تختلف عن public.

• REST API: تبقى نقاط نهاية API كما هي (/rest/v1/table_name)، لكن PostgREST يعرض الجداول من المخططات الأخرى بشكل افتراضي. قد تحتاج إلى إدارة الوصول عبر الأدوار والتخويلات في PostgreSQL إذا كنت ترغب في التحكم في وصول مستوى المخطط بشكل دقيق بالإضافة إلى RLS القياسي. إذا كان هناك تداخل في الأسماء (نفس اسم الجدول في public ومخطط آخر)، قد تحتاج إلى تكوين محدد أو استخدام RPC. تحقق من وثائق PostgREST لمعالجة رؤية المخطط إذا لزم الأمر.
• مكتبات العملاء: تعمل مكتبات العملاء بسلاسة. يمكنك ببساطة الإشارة إلى اسم الجدول كالمعتاد:

// الوصول إلى جدول في 'private_schema' (بافتراض أن RLS/الأذونات تسمح بذلك)
const { data, error } = await supabase
  .from('sensitive_data') // لا حاجة لإضافة بادئة مع اسم المخطط هنا
  .select('*')
  .eq('id', 1);

يتولى Supabase التعامل مع رسم اسم الجدول إلى المخطط الصحيح خلف الكواليس. تأكد من أن سياسات RLS الخاصة بك تشير بشكل صحيح إلى الجداول إذا كانت تتضمن استعلامات أو وظائف عبر المخطط.

تعد استخدام المخططات المخصصة ممارسة قياسية في PostgreSQL يدعمها Supabase بالكامل، مما يسمح بتنظيم قاعدة بيانات أكثر هيكلة.

9. الخاتمة

يوفر Supabase API وسيلة فعالة بشكل ملحوظ لبناء التطبيقات من خلال توفير وصول فوري وآمن وقابل للتوسع إلى قاعدة بيانات PostgreSQL الخاصة بك. من نقاط نهاية REST التي تم إنشاؤها تلقائيًا والمكتبات المفيدة إلى الأمان القوي الذي يوفره أمان مستوى الصف وقابلية التمدد التي تقدمها وظائف Edge، يمكّن Supabase المطورين من التركيز على بناء الميزات بدلاً من البنية التحتية للواجهة الخلفية المكررة.

من خلال فهم المفاهيم الأساسية - مفاتيح API، RLS، هيكل REST، إنشاء الأنواع، والوظائف المخصصة - يمكنك الاستفادة بشكل فعال من القوة الكاملة لمنصة Supabase. تذكر أن تعطي الأولوية للأمان.