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

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

إنشاء مفتاح Gemini API أو الاطّلاع عليه

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

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

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

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

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

إدارة مفاتيح واجهة برمجة التطبيقات في 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 غير مرتبط بمؤسسة لإنشاء مفاتيحكم.

إعداد البيئة

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

استخدام متغيّرات البيئة (مُقترَح)

اضبطوا متغيّر البيئة GEMINI_API_KEY أو GOOGLE_API_KEY. ترصد مكتبات برامج Gemini API هذه المتغيّرات وتستخدمها تلقائيًا. إذا تم ضبط كليهما، تكون الأولوية لـ 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

توفير مفتاح واجهة برمجة التطبيقات بشكلٍ صريح في الرمز

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

from google import genai

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

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how AI works in a few words"
)
print(response.text)

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

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

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

main();

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
)

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

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.5-flash",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

package com.example;

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().apiKey("YOUR_API_KEY").build();

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-3.5-flash",
            "Explain how AI works in a few words",
            null);

    System.out.println(response.text());
  }
}

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent"       -H 'Content-Type: application/json'       -H "x-goog-api-key: YOUR_API_KEY"       -X POST       -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "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 Console.
2. تحديث تطبيقكم: انشروا الرمز باستخدام المفتاح الجديد.
3. إيقاف المفتاح الذي تم اختراقه أو حذفه: أوقفوا المفتاح المسرب في Cloud Console بعد التحقّق من المفتاح الجديد. لا تحذفوا المفتاح القديم إلى أن يصبح المفتاح الجديد نشطًا بالكامل لتجنُّب توقّف التطبيق.
4. تدقيق الاستخدام: اطّلِعوا على سجلّات الفوترة واستخدام واجهة برمجة التطبيقات في Google Cloud Console لتحديد النشاط غير المصرّح به.

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

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

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

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

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

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

لمواصلة استخدام Gemini API بعد 19 يونيو 2026، يجب تأمين أي مفاتيح غير مقيدة.

قصر استخدام المفتاح على Gemini API فقط من خلال AI Studio

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

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

قصر استخدام المفتاح على خدمات أخرى من خلال Google Cloud Console

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

1. انتقِلوا إلى صفحة بيانات الاعتماد في Google Cloud Console.
2. اختاروا المشروع ومفتاح واجهة برمجة التطبيقات.
3. ضمن قيود واجهة برمجة التطبيقات، اختاروا تقييد المفتاح.
4. من القائمة المنسدلة، اختاروا واجهات برمجة التطبيقات التي تريدون أن يتمكّن هذا المفتاح من الوصول إليها. لا تختاروا Generative Language API.
5. انقروا على حفظ. أنشئوا مفتاحًا منفصلاً ومقيّدًا في 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.