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

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

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

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

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

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

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

• مفاتيح المصادقة تلقائيًا: يتم تلقائيًا إنشاء جميع مفاتيح واجهة برمجة التطبيقات الجديدة في Google AI Studio كمفاتيح مصادقة.
• رفض المفاتيح غير المقيدة: ترفض 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 غير مرتبط بمؤسسة لإنشاء مفاتيحكم.

إعداد البيئة

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

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

اضبطوا متغيّر البيئة 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

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

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

from google import genai

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

interaction = client.interactions.create(
    model="gemini-3.5-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.5-flash",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.output_text);
}

main();

package main

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

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)
    }

    interaction, err := client.Interactions.NewModel(ctx, interactions.NewModelParams{
        Model: "gemini-3.5-flash",
        Input: interactions.Input{
            String: "Explain how AI works in a few words",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range interaction.Steps {
        if step.ModelOutput != nil {
            for _, content := range step.ModelOutput.Content {
                if content.Text != nil {
                    fmt.Println(content.Text.Text)
                }
            }
        }
    }
}

package com.example;

import com.google.genai.Client;
import com.google.genai.interactions.models.interactions.CreateModelInteractionParams;
import com.google.genai.interactions.models.interactions.Interaction;

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

    CreateModelInteractionParams params =
        CreateModelInteractionParams.builder()
            .input("Explain how AI works in a few words")
            .model("gemini-3.5-flash")
            .build();

    Interaction interaction = client.interactions.create(params);

    interaction.steps().forEach(step -> {
      if (step.isModelOutput()) {
        step.asModelOutput().content().ifPresent(contents -> {
          contents.forEach(content -> {
            content.text().ifPresent(text -> System.out.println(text.text()));
          });
        });
      }
    });
  }
}

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.5-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 Console.
2. تحديث تطبيقكم: انشروا الرمز باستخدام المفتاح الجديد.
3. إيقاف المفتاح الذي تم اختراقه أو حذفه: أوقفوا المفتاح المسرب في Cloud Console بعد التحقّق من المفتاح الجديد. لا تحذفوا المفتاح القديم إلى أن يصبح المفتاح الجديد نشطًا بالكامل لتجنُّب توقّف التطبيق عن العمل.
4. تدقيق الاستخدام: اطّلِعوا على سجلّات الفوترة واستخدام واجهة برمجة التطبيقات في Google Cloud Console لتحديد النشاط غير المصرّح به.

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

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

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

تحدّ القيود المفروضة على المصدر عناوين 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 Console)

إذا كان المفتاح تتم مشاركته مع Google APIs الأخرى (لا يُنصح بذلك)، يمكنكم تقييده في Cloud Console. ملاحظة: ستفشل طلبات 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.