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

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

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

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

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

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

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

• الإعداد التلقائي لمفاتيح المصادقة: يتم تلقائيًا إنشاء جميع مفاتيح واجهة برمجة التطبيقات الجديدة التي يتم إنشاؤها في Google AI Studio كمفاتيح مصادقة.
• في 19 يونيو 2026: سترفض واجهة Gemini API الطلبات الواردة من المفاتيح العادية غير المحظورة، ولكن ستستمر المفاتيح العادية التي تم تطبيق قيود صريحة عليها في العمل. يمنع هذا الحظر الاستخدام غير المصرّح به للمفاتيح التي قد تتم مشاركتها بشكل علني أو ربطها بخدمات أخرى.
• في سبتمبر 2026، سترفض Gemini API الطلبات الواردة من مفاتيح Standard. عليك نقل البيانات إلى مفاتيح مصادقة قبل هذا التاريخ لتجنُّب انقطاع الخدمة. احرص على نقل البيانات إلى مفاتيح مصادقة قبل سبتمبر 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. بعد الاستيراد، انتقِل إلى صفحة مفاتيح واجهة برمجة التطبيقات في لوحة البيانات لإنشاء مفتاح في هذا المشروع.

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

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

يُرجى التواصل مع مشرف مشروع على السحابة الإلكترونية في 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.