استخدام مفاتيح واجهة برمجة التطبيقات في Gemini

لاستخدام Gemini API، يجب مصادقة طلباتك. يمكنك المصادقة باستخدام مفتاح واجهة برمجة تطبيقات عادي أو مفتاح تفويض.

إنشاء مفتاح Gemini API أو عرضه

أنواع مفاتيح واجهة برمجة التطبيقات: العادية مقابل مفاتيح التفويض

تتيح مفاتيح واجهة برمجة التطبيقات الوصول إلى Gemini API، ولكن تختلف خصائص الأمان الخاصة بها. نحن بصدد نقل Gemini API من مفاتيح واجهة برمجة التطبيقات العادية إلى مفاتيح التفويض لتحسين الأمان:

• مفاتيح واجهة برمجة التطبيقات العادية: يمكنك ربط الطلبات بمشروع على Google Cloud لأغراض الفوترة والحصص. لا تحدّد المفاتيح العادية هوية المتصل، ما يحدّ من دقة الأذونات وعناصر التحكّم في الوصول التي يمكنها توفيرها.
• مفاتيح التفويض (المصادقة): تكون مرتبطة مباشرةً بحساب خدمة Google Cloud. عند استخدام مفتاح تفويض، تتم معالجة طلباتك بموجب هوية حساب الخدمة المرتبط، ما يتيح التحكّم الدقيق في الوصول. تقتصر مفاتيح التفويض على Generative Language API (Gemini API) تلقائيًا، وتوفّر إجراءات سريعة لتنفيذ السياسات المتعلقة بالمفاتيح المسرَّبة، ما يؤدي إلى إيقاف استخدام المفاتيح المسرَّبة التي ترصدها أنظمتنا بسرعة.

لضمان الاستخدام الآمن، سينتقل Gemini API من المفاتيح العادية إلى مفاتيح المصادقة:

• مفاتيح المصادقة التلقائية: اعتبارًا من 28 مايو 2026، سيتم تلقائيًا إنشاء جميع مفاتيح واجهة برمجة التطبيقات الجديدة في Google AI Studio كمفاتيح مصادقة.
• رفض المفاتيح غير المقيَّدة: ترفض Gemini API الطلبات من المفاتيح العادية غير المقيَّدة. وستبقى مفاتيح واجهة برمجة التطبيقات العادية التي تم تطبيق قيود صريحة عليها صالحة. يمنع هذا التقييد الاستخدام غير المصرَّح به للمفاتيح التي قد تتم مشاركتها بشكل علني أو ربطها بخدمات أخرى.

إدارة مفاتيح واجهة برمجة التطبيقات في Google AI Studio

يمكنك إدارة مشاريعك ومفاتيحك مباشرةً في Google AI Studio.

مشاريع Google Cloud

يرتبط كل مفتاح Gemini API بمشروع على Google Cloud. تتم إدارة الفوترة والمتعاونين والأذونات من خلال مشاريع Google Cloud. ويوفّر Google AI Studio واجهة بسيطة للوصول إلى هذه المشاريع.

• المشروع التلقائي: إذا كنت مستخدمًا جديدًا، ينشئ Google AI Studio تلقائيًا مشروعًا تلقائيًا على Google Cloud ومفتاح واجهة برمجة تطبيقات بعد قبولك بنود الخدمة. يمكنك إعادة تسمية هذا المشروع من خلال الانتقال إلى عرض المشاريع في لوحة البيانات.
• المشاريع الحالية: إذا كان لديك حساب على Google Cloud، لن ينشئ AI Studio مشروعًا تلقائيًا. بدلاً من ذلك، عليك استيراد مشاريعك الحالية.

استيراد المشاريع

لا يعرض Google AI Studio تلقائيًا جميع مشاريعك على Google Cloud. يجب استيراد المشاريع التي تريد استخدامها:

1. انتقِل إلى Google AI Studio.
2. افتح لوحة البيانات من اللوحة اليمنى واختَر المشاريع.
3. انقر على الزر استيراد المشاريع.
4. ابحث عن مشروع Google Cloud الذي تريد استيراده واختَره، ثم انقر على استيراد.
5. بعد الاستيراد، انتقِل إلى صفحة مفاتيح واجهة برمجة التطبيقات في لوحة البيانات لإنشاء مفتاح في ذلك المشروع.

تحديد مشاكل أذونات إنشاء المفاتيح وحلّها

إذا لم يكن الزر إنشاء مفتاح واجهة برمجة التطبيقات متاحًا وظهرت الرسالة: "ليس لديك الإذن بإنشاء مفتاح في هذا المشروع"، يعني ذلك أنّك لا تملك أذونات "إدارة الهوية وإمكانية الوصول" المطلوبة.

اطلب من مشرف مشروعك على السحابة الإلكترونية أو مشرف مؤسستك على Google Cloud منحك دورًا يتضمّن الأذونات التالية (مثل "محرِّر المشروع").

• ‫resourcemanager.projects.get: يسمح هذا الإذن لـ AI Studio بالتحقّق من المشروع.
• ‫apikeys.keys.create: يسمح بإنشاء المفاتيح.
• ‫serviceusage.services.enable: يضمن تفعيل Generative Language API.
• ‫iam.serviceAccounts.create: مطلوب لإنشاء حساب الخدمة المرتبط.
• ‫iam.serviceAccountApiKeyBindings.create: لربط حساب الخدمة بمفتاح واجهة برمجة التطبيقات

إذا لم تتمكّن من الحصول على إذن وصول إداري، يمكنك إنشاء مشروع جديد على Google Cloud غير مرتبط بمؤسسة لإنشاء مفاتيحك.

مفاتيح غير معروفة في صفحة "الاستخدام"

تُجمِّع صفحة الاستخدام في Google AI Studio الطلبات التي لا يمكن مطابقتها مع مفتاح واجهة برمجة تطبيقات مُسمّى في المشروع ضمن (مفاتيح غير معروفة). ويشمل ذلك المفاتيح التي تم حذفها قبل أكثر من 30 يومًا، والمفاتيح التي لا تتضمّن اسمًا معروضًا، والطلبات التي تم إجراؤها باستخدام بيانات اعتماد أخرى، مثل OAuth.

إنشاء المفاتيح في وحدة تحكّم Google Cloud

لا يعرض Google AI Studio سوى المفاتيح غير المقيّدة أو المقيّدة بـ Gemini API. إذا لم تتمكّن من استخدام AI Studio أو أردت إدارة جميع مفاتيح واجهة برمجة التطبيقات في مكان واحد، اتّبِع مستندات Cloud حول إنشاء مفتاح واجهة برمجة التطبيقات. يتطلّب إنشاء مفتاح واجهة برمجة التطبيقات Gemini ربطه بحساب خدمة.

إعداد البيئة

بعد الحصول على مفتاح، اضبط بيئتك لاستخدامه بأمان في تطبيقاتك.

الخيار 1: استخدام متغيّرات البيئة (يُنصح به)

اضبط متغيّر البيئة GEMINI_API_KEY أو GOOGLE_API_KEY. تكتشف مكتبات عميل واجهة برمجة التطبيقات Gemini وتستخدم هذه المتغيّرات تلقائيًا. وفي حال ضبط كليهما، ستكون الأولوية لسياسة GOOGLE_API_KEY.

اختَر نظام التشغيل لضبط المتغيّر:

~/.bashrc

touch ~/.bashrc && open ~/.bashrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.bashrc

~/.zshrc

touch ~/.zshrc && open ~/.zshrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.zshrc

الخيار 2: تقديم مفتاح واجهة برمجة التطبيقات بشكل صريح في الرمز البرمجي

يمكنك تمرير مفتاح واجهة برمجة التطبيقات بشكل صريح عند إعداد العميل. لا تفعل ذلك إلا إذا لم تتمكن من استخدام متغيرات البيئة.

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.output_text);
}

main();

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = Client.builder().apiKey("YOUR_API_KEY").build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain how AI works in a few sentences."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey: "YOUR_API_KEY",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Explain how AI works in a few sentences."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain how AI works in a few words"
  }'

الأمان وإدارة البيانات السرية

يجب التعامل مع مفتاح Gemini API ككلمة مرور. في حال اختراقها، يمكن للآخرين استهلاك الحصة المخصصة لمشروعك، وتحمُّل رسوم فوترة غير متوقعة، والوصول إلى الموارد الخاصة.

قواعد الأمان المُهمّة

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

أفضل الممارسات المتعلّقة بإدارة الأسرار

• متغيّرات البيئة: يمكنك قراءة المفاتيح من متغيّرات البيئة بدلاً من ملفات الإعداد.
• ‫Secret Manager: في مرحلة الإنتاج، يمكنك تخزين مفاتيحك في مخزن آمن للبيانات السرية، مثل Google Cloud Secret Manager.
• تنبيهات الفوترة: يمكنك إعداد تنبيهات الفوترة في Google Cloud Console لإعلامك في حال ارتفاع معدّل الاستخدام أو التكاليف.

قائمة التحقّق من الاستجابة للتسريب

إذا كنت تشكّ في أنّه تم تسريب مفتاح واجهة برمجة التطبيقات:

1. إنشاء مفتاح جديد: يمكنك إنشاء مفتاح بديل في Google AI Studio أو وحدة تحكّم Cloud.
2. تحديث تطبيقك: يمكنك نشر الرمز باستخدام المفتاح الجديد.
3. إيقاف المفتاح الذي تم اختراقه أو حذفه: يمكنك إيقاف المفتاح الذي تم تسريبه في وحدة تحكّم Cloud بعد التحقّق من المفتاح الجديد. لا تحذف المفتاح القديم حتى يتم تفعيل المفتاح الجديد بالكامل لتجنُّب توقُّف التطبيق عن العمل.
4. تدقيق الاستخدام: يمكنك مراجعة سجلّات الفوترة واستخدام واجهة برمجة التطبيقات في وحدة تحكّم Google Cloud لتحديد أي نشاط غير مصرَّح به.

تقييد مفاتيحك وتأمينها

تؤدي إضافة قيود إلى مفاتيح واجهة برمجة التطبيقات إلى تقليل الضرر المحتمل في حال اختراق أحد المفاتيح.

تطبيق قيود على مصدر الطلب

تحدّ قيود المصدر من عناوين IP أو المواقع الإلكترونية أو التطبيقات التي يمكنها استخدام مفتاحك.

1. انتقِل إلى صفحة بيانات الاعتماد في Google Cloud Console.
2. اختَر مشروعك، وانقر على اسم مفتاح واجهة برمجة التطبيقات الذي تريد حظره.
3. ضمن قيود التطبيق، اختَر عناوين IP (أو نوع القيود المناسب لبيئتك).
4. حدِّد عناوين IP أو النطاقات المسموح بها، ثم انقر على حفظ.

تأمين مفاتيح واجهة برمجة التطبيقات العادية غير المقيّدة

لمواصلة استخدام Gemini API، عليك تأمين أي مفاتيح غير مقيّدة.

الطريقة "أ": حصر استخدام المفتاح بـ Gemini API فقط (AI Studio)

إذا كنت تستخدم المفتاح لواجهة Gemini API فقط، يمكنك تأمينه مباشرةً في AI Studio:

1. في صفحة مفاتيح واجهة برمجة التطبيقات في Google AI Studio، ابحث عن المفاتيح التي تحمل التصنيف غير مشروط.
2. مرِّر مؤشر الماوس فوق التصنيف وانقر على إضافة قيود في مربّع الحوار.
3. اختَر الحصر على Gemini API فقط.
4. انقر على تقييد المفتاح للتأكيد.

الطريقة "ب": حصر استخدام المفتاح في خدمات أخرى (وحدة تحكّم Google Cloud)

إذا تمت مشاركة المفتاح مع واجهات Google APIs أخرى (لا يُنصح بذلك)، يمكنك حظره في وحدة تحكّم Cloud. ملاحظة: ستتعذّر طلبات بيانات من واجهة برمجة التطبيقات Gemini API التي تستخدم هذا المفتاح بعد تطبيق هذه القيود.

1. انتقِل إلى صفحة بيانات الاعتماد في Google Cloud Console.
2. اختَر المشروع ومفتاح واجهة برمجة التطبيقات.
3. ضمن قيود واجهة برمجة التطبيقات، استخدِم القائمة المنسدلة اختيار قيود واجهة برمجة التطبيقات لاختيار واجهات برمجة التطبيقات التي تريد أن يصل إليها هذا المفتاح. لا تختَر Generative Language API.
4. انقر على حفظ. يُرجى إنشاء مفتاح منفصل ومقيّد في AI Studio لمواصلة استخدام Gemini API.

المفاتيح غير النشطة المحظورة

اعتبارًا من 7 مايو 2026، ستحظر Gemini API مفاتيح واجهة برمجة التطبيقات غير المقيّدة التي كانت غير نشطة لفترة طويلة. تظهر علامة محظور لهذه المفاتيح في AI Studio. يجب إنشاء مفتاح جديد أو استخدام مفتاح حالي محظور للمتابعة.

نقل البيانات إلى مفتاح مصادقة

اتّبِع الخطوات التالية لإنشاء مفتاح جديد لواجهة برمجة التطبيقات الخاصة بالمصادقة وتحديث تطبيقاتك:

1. انتقِل إلى صفحة مفاتيح واجهة برمجة تطبيقات الاستوديو في AI Studio.
2. اطّلِع على عمود نوع المفتاح لتحديد أي مفاتيح مُدرَجة على أنّها عادية.
3. انقر على إنشاء مفتاح واجهة برمجة التطبيقات لإنشاء مفتاح جديد. يتم إنشاء جميع المفاتيح الجديدة في AI Studio تلقائيًا كمفاتيح مصادقة.
4. انسخ مفتاح واجهة برمجة التطبيقات الجديد للمصادقة.
5. عدِّل الرمز البرمجي للتطبيق ومتغيّرات البيئة وأي إعدادات نشر لاستخدام مفتاح واجهة برمجة التطبيقات الجديد للمصادقة.
6. اختبِر تطبيقك للتأكّد من أنّه يعمل بشكل صحيح مع المفتاح الجديد.
7. بعد إثبات الملكية، احذف مفتاح الزيارات القديم أو ألغِه لمنع إساءة استخدامه.

القيود

يفرض Google AI Studio القيود التالية على إدارة المشاريع والمفاتيح:

• يمكنك إنشاء 10 مشاريع كحدّ أقصى في كل مرة من صفحة المشاريع في Google AI Studio.
• تعرض صفحتا مفاتيح واجهة برمجة التطبيقات والمشاريع بحد أقصى 100 مفتاح و50 مشروعًا.
• يتم عرض مفاتيح واجهة برمجة التطبيقات غير المقيّدة أو المقيّدة تحديدًا بـ Generative Language API (واجهة برمجة التطبيقات Gemini API) فقط.

لإدارة المشاريع المتقدّمة أو تعديل المفاتيح التي تتضمّن قيودًا أخرى، استخدِم صفحة بيانات الاعتماد في Google Cloud Console.