أصبحت Interactions API متاحة الآن للجميع. ننصحك باستخدام واجهة برمجة التطبيقات هذه للوصول إلى جميع أحدث الميزات والنماذج.

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

بيانات الاعتماد في الوكلاء المُدارين

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

قيم المفتاح السرّي قابلة للكتابة فقط. وبعد تخزينها، لا يتم عرضها مطلقًا من خلال أي نقطة نهاية، وبالتالي لا يمكن لأي وكيل تم اختراقه إعادة قراءة الرموز المميزة التي يستخدمها.

المكان الأساسي الذي تستخدم فيه بيانات الاعتماد هو قائمة الشبكة المسموح بها على environment.network. يجب تخزين السر أولاً:

Python

from google import genai

client = genai.Client()

credential = client.credentials.create(
    id="github-production",
    type="bearer_token",
    token="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)

print(f"Credential ID: {credential.id}, Status: {credential.status}")

JavaScript

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

const client = new GoogleGenAI({});

const credential = await client.credentials.create({
    id: "github-production",
    type: "bearer_token",
    token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

console.log(`Credential ID: ${credential.id}, Status: ${credential.status}`);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "github-production",
    "type": "bearer_token",
    "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'

بعد ذلك، أرفِقها بالنطاق الذي تصادق عليه:

Python

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Triage the open issues in my-org/my-repo.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {"domain": "api.github.com", "credential": "github-production"},
                {"domain": "*"},
            ]
        },
    },
)

JavaScript

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Triage the open issues in my-org/my-repo.",
    environment: {
        type: "remote",
        network: {
            allowlist: [
                { domain: "api.github.com", credential: "github-production" },
                { domain: "*" },
            ],
        },
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Triage the open issues in my-org/my-repo.",
    "environment": {
        "type": "remote",
        "network": {
            "allowlist": [
                { "domain": "api.github.com", "credential": "github-production" },
                { "domain": "*" }
            ]
        }
    }
}'

يُجري الوكيل الآن طلبات مصادقة إلى api.github.com، ولا يتوفّر الرمز المميز داخل البيئة التجريبية.

أنواع بيانات الاعتماد

تحتوي كل بيانات اعتماد على type تحدّد الحقول التي تقبلها وكيفية تطبيق الوكيل لها.

النوع	حالة الاستخدام	السلوك
`bearer_token`	رموز الدخول الشخصية ورموز البوت ومفاتيح واجهة برمجة التطبيقات الثابتة	يُدرج الخادم الوكيل الرمز المميز كعنوان طلب. لا توجد منطق لإعادة التحميل.
`oauth2`	تطبيقات OAuth وتدفقات التفويض من المستخدم	يستبدل الخادم الوكيل الرمز المميز لإعادة التحميل برموز الدخول ويعيد تحميلها عند انتهاء صلاحيتها.
`environment_variable`	حِزم تطوير البرامج (SDK) للعملاء التي تقرأ الأسرار من بيئة العملية	تتلقّى بيئة الوكيل عنصرًا نائبًا. يستبدل الخادم الوكيل السر الفعلي في الطلبات الصادرة.

استخدام بيانات الاعتماد في قائمة الشبكة المسموح بها

أضِف credential إلى قاعدة القائمة المسموح بها، وسيصادق الخادم الوكيل على كل طلب صادر إلى هذا النطاق. هذه هي الطريقة المقترَحة لمنح أحد الوكلاء إذن الوصول إلى واجهة برمجة تطبيقات خاصة أو مستودع خاص أو حزمة خاصة.

يمكنك دمج قواعد مصادق عليها وغير مصادق عليها في قائمة السماح نفسها:

Python

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Sync the open Jira issues into the tracking sheet in my repo.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/your-org/backend",
                "target": "/backend-app",
            }
        ],
        "network": {
            "allowlist": [
                {"domain": "github.com", "credential": "github-production"},
                {"domain": "api.atlassian.com", "credential": "jira-oauth"},
                {"domain": "*.googleapis.com"},
            ]
        },
    },
)

JavaScript

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Sync the open Jira issues into the tracking sheet in my repo.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/your-org/backend",
                target: "/backend-app",
            },
        ],
        network: {
            allowlist: [
                { domain: "github.com", credential: "github-production" },
                { domain: "api.atlassian.com", credential: "jira-oauth" },
                { domain: "*.googleapis.com" },
            ],
        },
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Sync the open Jira issues into the tracking sheet in my repo.",
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/your-org/backend",
                "target": "/backend-app"
            }
        ],
        "network": {
            "allowlist": [
                { "domain": "github.com", "credential": "github-production" },
                { "domain": "api.atlassian.com", "credential": "jira-oauth" },
                { "domain": "*.googleapis.com" }
            ]
        }
    }
}'

بما أنّ الخادم الوكيل يحلّ بيانات الاعتماد لكل طلب، فإنّ بيانات اعتماد oauth2 تعيد تحميل رمز الدخول بشكل غير ملحوظ. لا يتم إيقاف التفاعل الطويل الأمد عند انتهاء صلاحية رمز الدخول.

الجمع بين `credential` و`transform`

تقبل قواعد القائمة المسموح بها أيضًا كائنًا مضمّنًا transform يضبط العناوين مباشرةً في القاعدة. يتم تطبيق الآليتَين من خلال وكيل الخروج على الشبكة، لذا في كلتا الحالتَين، لا توجد قيمة العنوان أبدًا داخل البيئة التجريبية. يمكن أن يظهر كلا الحقلين في القاعدة نفسها.

إعدادات القاعدة	السلوك
`credential` فقط	يحلّ الخادم الوكيل بيانات الاعتماد ويُدرج عنوانه في كل طلب يتم إرساله إلى النطاق.
`transform` فقط	إدخال عناوين ثابتة يتم إرسال العناوين التي تكتبها كما هي.
كلاهما	يتم تطبيق بيانات الاعتماد أولاً، ثم يتم دمج `transform` في الأعلى. يفوز عنوان `transform` صريح إذا كان كلاهما يضبط المفتاح نفسه.
لا ينطبق أي مما سبق	يُسمح بالنطاق ولا يتم إدخال أي عناوين.

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

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

{
    "domain": "api.atlassian.com",
    "credential": "jira-oauth",
    "transform": {
        "X-Atlassian-Workspace": "my-workspace-id"
    }
}

لنقل سرّ من transform مضمّن إلى بيانات اعتماد، خزِّنه باستخدام POST /credentials، واستبدِل عنوان المصادقة في transform بـ "credential": "<id>"، واترك بقية عنصر transform كما هي.

استخدام بيانات الاعتماد مع خوادم MCP

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

Python

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Create a new issue in my-org/my-repo",
    environment="remote",
    tools=[{
        "type": "mcp_server",
        "name": "github",
        "url": "https://api.githubcopilot.com/mcp",
        "credential": "github-production",
    }],
)

JavaScript

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Create a new issue in my-org/my-repo",
    environment: "remote",
    tools: [{
        type: "mcp_server",
        name: "github",
        url: "https://api.githubcopilot.com/mcp",
        credential: "github-production",
    }],
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Create a new issue in my-org/my-repo",
    "environment": "remote",
    "tools": [
        {
            "type": "mcp_server",
            "name": "github",
            "url": "https://api.githubcopilot.com/mcp",
            "credential": "github-production"
        }
    ]
}'

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

{
    "type": "mcp_server",
    "name": "jira",
    "url": "https://jira.atlassian.com/mcp",
    "credential": "jira-oauth",
    "headers": {
        "X-Atlassian-Workspace": "my-workspace-id"
    }
}

لنقل سرّ من headers المضمّن إلى بيانات اعتماد، خزِّنه باستخدام POST /credentials واستبدِل إدخال المصادقة في headers بـ credential. اترك العناوين الأخرى في مكانها.

استخدام بيانات الاعتماد كمتغيّرات بيئة

تقرأ بعض مكتبات البرامج المساعدة للعملاء الأسرار من بيئة العملية بدلاً من قبولها كعناوين طلبات. تُعدّ برامج socket-mode وبرامج long-polling من الحالات الشائعة.

ربط بيانات اعتماد environment_variable باسم متغيّر ضمن environment.env:

Python

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Run the sync script and check notifications.",
    environment={
        "type": "remote",
        "env": {
            "NODE_ENV": "production",
            "SLACK_BOT_TOKEN": {"credential": "slack-bot-token"},
        },
    },
)

JavaScript

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Run the sync script and check notifications.",
    environment: {
        type: "remote",
        env: {
            NODE_ENV: "production",
            SLACK_BOT_TOKEN: { credential: "slack-bot-token" },
        },
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Run the sync script and check notifications.",
    "environment": {
        "type": "remote",
        "env": {
            "NODE_ENV": "production",
            "SLACK_BOT_TOKEN": { "credential": "slack-bot-token" }
        }
    }
}'

يقبل env السلاسل الحرفية ومراجع بيانات الاعتماد جنبًا إلى جنب. يتم إدخال سلسلة حرفية في الحاوية كمتغيّر نص عادي.

لا يمكن أن يكون مرجعًا لبيانات الاعتماد. يتلقّى المتغيّر العنصر النائب __GEMINI_CRED_<credential-id>__، ويستبدله الخادم الوكيل بالبيانات السرية الفعلية فقط للطلبات الصادرة إلى نطاق في trusted_domains لبيانات الاعتماد. ويتم رفض أي طلب لنطاق آخر، وبالتالي لا يخرج الرمز السري من المحيط ولا يتم إرسال العنصر النائب بدلاً منه.

اضبط trusted_domains على كل بيانات اعتماد environment_variable. وهو عنصر التحكّم الذي يحدّد نطاق استخدام كلمة المرور.

إنشاء بيانات اعتماد

يحتاج كل طلب إنشاء إلى type، بالإضافة إلى أي حقول يتطلبها هذا النوع.

عند طلب REST مباشرةً، تستخدم جميع أسماء الحقول snake_case. يؤدي إرسال حقل camelCase إلى عرض 400.

رمز حامل مميز

لا تحتاج بيانات اعتماد الرمز المميز لحاملها سوى token:

Python

credential = client.credentials.create(
    id="github-production",
    type="bearer_token",
    token="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)

JavaScript

const credential = await client.credentials.create({
    id: "github-production",
    type: "bearer_token",
    token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "github-production",
    "type": "bearer_token",
    "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'

لا تعرض الاستجابة سوى البيانات الوصفية، ولا تعرض الرمز المميز أبدًا:

{
  "id": "github-production",
  "type": "bearer_token",
  "status": "active",
  "create_time": "2026-07-15T10:00:00.000000000Z",
  "update_time": "2026-07-15T10:00:00.000000000Z"
}

يرسل الخادم الوكيل القيمة Authorization: Bearer <token> تلقائيًا. استبدِل header_name وprefix لاستهداف خدمة تتوقّع شيئًا آخر:

Python

credential = client.credentials.create(
    id="my-api-key",
    type="bearer_token",
    token="key_xxxxxxxxxxxx",
    header_name="x-goog-api-key",
    prefix="",
)

JavaScript

const credential = await client.credentials.create({
    id: "my-api-key",
    type: "bearer_token",
    token: "key_xxxxxxxxxxxx",
    header_name: "x-goog-api-key",
    prefix: "",
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "my-api-key",
    "type": "bearer_token",
    "token": "key_xxxxxxxxxxxx",
    "header_name": "x-goog-api-key",
    "prefix": ""
}'

يؤدي هذا الإعداد إلى إنشاء العنوان x-goog-api-key: key_xxxxxxxxxxxx.

يوضّح الجدول التالي كيفية دمج header_name وprefix:

التهيئة	عنوان مُدخَل
`{"token": "ghp_xxx"}`	`Authorization: Bearer ghp_xxx`
`{"token": "sk_live_xxx"}`	`Authorization: Bearer sk_live_xxx`
`{"token": "key_xxx", "header_name": "x-goog-api-key", "prefix": ""}`	`x-goog-api-key: key_xxx`
`{"token": "mytoken", "header_name": "X-API-Token", "prefix": ""}`	`X-API-Token: mytoken`

OAuth2

تتطلّب بيانات اعتماد OAuth2 توفّر client_id وclient_secret وrefresh_token وtoken_url. الحقل scopes اختياري:

Python

credential = client.credentials.create(
    id="jira-oauth",
    type="oauth2",
    client_id="my-client-id",
    client_secret="my-client-secret",
    token_url="https://auth.atlassian.com/oauth/token",
    refresh_token="rt_xxxxxxxxxxxxxxxxxxxx",
    scopes=["read:jira-work", "write:jira-work"],
)

JavaScript

const credential = await client.credentials.create({
    id: "jira-oauth",
    type: "oauth2",
    client_id: "my-client-id",
    client_secret: "my-client-secret",
    token_url: "https://auth.atlassian.com/oauth/token",
    refresh_token: "rt_xxxxxxxxxxxxxxxxxxxx",
    scopes: ["read:jira-work", "write:jira-work"],
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "jira-oauth",
    "type": "oauth2",
    "client_id": "my-client-id",
    "client_secret": "my-client-secret",
    "token_url": "https://auth.atlassian.com/oauth/token",
    "refresh_token": "rt_xxxxxxxxxxxxxxxxxxxx",
    "scopes": ["read:jira-work", "write:jira-work"]
}'

يؤدي إنشاء بيانات اعتماد OAuth2 إلى إجراء عملية تبادل رموز مميزة مباشرة مع token_url للتأكّد من أنّ الإعدادات تعمل. لا يتم تخزين بيانات الاعتماد إلا إذا أرجع مقدّم الخدمة ردًا ناجحًا يتضمّن رمزًا مميزًا access_token. يتم قبول الردود بتنسيق JSON وform-urlencoded.

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

{
  "error": {
    "message": "OAuth token validation failed with HTTP 403: {\"error\":\"unauthorized_client\",\"error_description\":\"refresh_token is invalid\"}",
    "code": "invalid_request"
  }
}

وبعد تخزينها، يعيد الخادم الوكيل إنشاء رموز الدخول عند انتهاء صلاحيتها. إذا كان مقدّم الخدمة يغيّر رموز الدخول المميزة بشكل دوري ويعرض رمزًا جديدًا أثناء عملية التحديث، سيحل الرمز الجديد محل الرمز المخزّن تلقائيًا.

متغيّر البيئة

تتطلّب بيانات اعتماد environment_variable توفّر value وinjection_location:

Python

credential = client.credentials.create(
    id="slack-bot-token",
    type="environment_variable",
    value="xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
    trusted_domains=["*.slack.com", "slack.com"],
    injection_location="header",
)

JavaScript

const credential = await client.credentials.create({
    id: "slack-bot-token",
    type: "environment_variable",
    value: "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
    trusted_domains: ["*.slack.com", "slack.com"],
    injection_location: "header",
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "slack-bot-token",
    "type": "environment_variable",
    "value": "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
    "trusted_domains": ["*.slack.com", "slack.com"],
    "injection_location": "header"
}'

يخبر الحقل injection_location الخادم الوكيل بمكان استبدال كلمة المرور في الطلب الصادر. يقبل هذا الحقل header أو query أو body، إما كسلسلة واحدة أو كمصفوفة عندما تحتاج الخدمة إلى أكثر من واحد:

"injection_location": ["header", "query"]

يحدث الاستبدال في المواقع الجغرافية التي تُدرجها فقط. ويتم رفض أي طلب يتضمّن العنصر النائب في أي مكان آخر بدلاً من إرساله.

لربط بيانات الاعتماد باسم متغيّر، يُرجى الاطّلاع على استخدام بيانات الاعتماد كمتغيّرات بيئة.

أرقام التعريف التي يتم إنشاؤها

الحقل id اختياري. احذفها وستنشئ الخدمة معرّفًا فريدًا عالميًا:

{
  "id": "9e545973-4330-49bb-9a44-930cea9fbe3c",
  "type": "bearer_token",
  "status": "active",
  "create_time": "2026-07-15T10:00:00.000000000Z",
  "update_time": "2026-07-15T10:00:00.000000000Z"
}

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

عرض قائمة ببيانات الاعتماد

أدرِج بيانات الاعتماد التابعة لمشروعك. استخدِم مَعلمات تقسيم الصفحات للتحكّم في حجم مجموعة الردود.

Python

response = client.credentials.list(page_size=10)
for credential in response.credentials:
    print(f"Credential ID: {credential.id}, Type: {credential.type}")

JavaScript

const response = await client.credentials.list({ page_size: 10 });
for (const credential of response.credentials) {
    console.log(`Credential ID: ${credential.id}, Type: ${credential.type}`);
}

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/credentials?page_size=10" \
-H "x-goog-api-key: $GEMINI_API_KEY"

تحتوي الاستجابة على بيانات وصفية فقط:

{
  "credentials": [
    {
      "id": "github-production",
      "type": "bearer_token",
      "status": "active",
      "create_time": "2026-07-15T10:00:00.000000000Z",
      "update_time": "2026-07-15T10:00:00.000000000Z"
    },
    {
      "id": "jira-oauth",
      "type": "oauth2",
      "status": "active",
      "create_time": "2026-07-15T10:05:00.000000000Z",
      "update_time": "2026-07-15T10:05:00.000000000Z"
    }
  ],
  "next_page_token": "Cj...5aE="
}

مرِّر next_page_token مرة أخرى كـ page_token لجلب الصفحة التالية. يتم حذف الحقل عندما لا تتوفّر نتائج أخرى.

المَعلمة	النوع	الوصف
`page_size`	عدد صحيح	الحدّ الأقصى لعدد بيانات الاعتماد في كل صفحة
`page_token`	سلسلة	الرمز المميّز من `next_page_token` لردّ سابق

الحصول على بيانات اعتماد

استرداد بيانات التعريف لبيانات اعتماد محدّدة من خلال رقم تعريفها

Python

credential = client.credentials.get(id="github-production")
print(f"Credential ID: {credential.id}, Status: {credential.status}")

JavaScript

const credential = await client.credentials.get("github-production");
console.log(`Credential ID: ${credential.id}, Status: ${credential.status}`);

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "x-goog-api-key: $GEMINI_API_KEY"

ستبدو الاستجابة مشابهة لما يلي:

{
  "id": "github-production",
  "type": "bearer_token",
  "status": "active",
  "create_time": "2026-07-15T10:00:00.000000000Z",
  "update_time": "2026-08-01T14:30:00.000000000Z"
}

سيؤدي طلب بيانات اعتماد غير متوفّرة إلى عرض 404:

{
  "error": {
    "message": "Result not found.; GetCredential call failed",
    "code": "not_found"
  }
}

تغيير بيانات اعتماد

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

يجب أن يتضمّن الطلب type، بالإضافة إلى الحقول التي تريد تغييرها. ستحتفظ الحقول التي لا تدرجها بقيمها الحالية.

تدوير رمز حامل مميز:

Python

credential = client.credentials.update(
    id="github-production",
    type="bearer_token",
    token="ghp_new_xxxxxxxxxxxxxxxxxxxx",
)

JavaScript

const credential = await client.credentials.update("github-production", {
    type: "bearer_token",
    token: "ghp_new_xxxxxxxxxxxxxxxxxxxx",
});

REST

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "type": "bearer_token",
    "token": "ghp_new_xxxxxxxxxxxxxxxxxxxx"
}'

تغيير رمز مميز لإعادة تحميل OAuth2:

Python

credential = client.credentials.update(
    id="jira-oauth",
    type="oauth2",
    refresh_token="rt_new_xxxxxxxxxxxxxxxxxxxx",
)

JavaScript

const credential = await client.credentials.update("jira-oauth", {
    type: "oauth2",
    refresh_token: "rt_new_xxxxxxxxxxxxxxxxxxxx",
});

REST

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/credentials/jira-oauth" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "type": "oauth2",
    "refresh_token": "rt_new_xxxxxxxxxxxxxxxxxxxx"
}'

يعكس الردّ update_time الجديد:

{
  "id": "jira-oauth",
  "type": "oauth2",
  "status": "active",
  "create_time": "2026-07-15T10:05:00.000000000Z",
  "update_time": "2026-08-01T14:30:00.000000000Z"
}

يتم تحديد type لبيانات الاعتماد عند إنشائها. لتغييرها، عليك حذف بيانات الاعتماد وإنشاء بيانات جديدة.

حذف بيانات اعتماد

احذف بيانات الاعتماد والبيانات السرية المخزّنة عندما لا تعود بحاجة إليها.

Python

client.credentials.delete(id="github-production")

JavaScript

await client.credentials.delete("github-production");

REST

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "x-goog-api-key: $GEMINI_API_KEY"

يؤدي الحذف الناجح إلى عرض عنصر فارغ:

{}

أي قاعدة أو أداة أو متغيّر بيئة في قائمة السماح لا يزال يشير إلى المعرّف لن يتمكّن من حلّ المشكلة، لذا عليك تعديلها أولاً.

مرجع الحقل

الحقول المشتركة في كل بيانات اعتماد:

الحقل	النوع	مطلوب	الوصف
`id`	سلسلة	لا	معرّف فريد يتم إنشاؤه كمعرّف فريد عالمي (UUID) عند حذفه.
`type`	سلسلة	نعم	إحدى القيم التالية: `bearer_token` أو `oauth2` أو `environment_variable`
`status`	سلسلة	للقراءة فقط	الحالة الحالية لبيانات الاعتماد
`create_time`	سلسلة	للقراءة فقط	الطابع الزمني للإنشاء وفقًا لمعيار RFC 3339
`update_time`	سلسلة	للقراءة فقط	الطابع الزمني RFC 3339 لآخر تعديل

حقول bearer_token:

الحقل	النوع	مطلوب	الوصف
`token`	سلسلة	نعم	للكتابة فقط تمثّل هذه السمة قيمة الرمز المميز.
`header_name`	سلسلة	لا	عنوان HTTP المطلوب إدخاله القيمة التلقائية هي `Authorization`.
`prefix`	سلسلة	لا	بادئة القيمة القيمة التلقائية هي `Bearer`. اضبط القيمة على `""` لعدم استخدام أيّ منها.

حقول oauth2:

الحقل	النوع	مطلوب	الوصف
`client_id`	سلسلة	نعم	معرّف عميل OAuth2
`client_secret`	سلسلة	نعم	للكتابة فقط سر عميل OAuth2
`refresh_token`	سلسلة	نعم	للكتابة فقط يُستخدم الرمز المميز لإعادة التحميل للحصول على رموز الدخول.
`token_url`	سلسلة	نعم	نقطة نهاية الرمز المميز لموفّر الخدمة
`scopes`	صفيف	لا	نطاقات OAuth المطلوب الحصول عليها.

حقول environment_variable:

الحقل	النوع	مطلوب	الوصف
`value`	سلسلة	نعم	للكتابة فقط تمثّل هذه السمة قيمة المفتاح السرّي.
`injection_location`	سلسلة أو مصفوفة	نعم	المكان الذي يجب استبدال المفتاح السري فيه واحدة أو أكثر من `header` أو `query` أو `body`
`trusted_domains`	صفيف	لا	أنماط النطاقات المسموح باستبدالها

الأخطاء

تعرض الأخطاء عنصر JSON يتضمّن message وcode:

{
  "error": {
    "message": "Credential 'github-production' already exists.; CreateCredential call failed",
    "code": "aborted"
  }
}

رموز حالة HTTP	`code`	السبب
400	`invalid_request`	الحقل المطلوب غير مضمَّن أو غير معروف أو غير متوافق مع `type` أو تعذّر إكمال عملية التحقّق من صحة OAuth2.
404	`not_found`	ما مِن بيانات اعتماد تحمل رقم التعريف هذا.
409	`aborted`	تتوفّر بيانات اعتماد بهذا المعرّف حاليًا.

يتم رفض الحقول غير المعروفة بدلاً من تجاهلها، ويشير الخطأ إلى اسم الحقل:

{
  "error": {
    "message": "Unknown parameter 'headerName'. Did you mean 'header_name'?",
    "code": "invalid_request"
  }
}

الخطوات التالية

البيئات: تعرَّف على طريقة تنفيذ الوكلاء للتعليمات البرمجية والاحتفاظ بالملفات.
نظرة عامة على الوكلاء: تعرَّف على المفاهيم الأساسية للوكلاء المُدارين.
إنشاء وكلاء مخصّصين: يمكنك تحديد الوكلاء الخاصين بك باستخدام AGENTS.md وSKILL.md.

بيانات الاعتماد في الوكلاء المُدارين

Python

JavaScript

REST

Python

JavaScript

REST

أنواع بيانات الاعتماد

استخدام بيانات الاعتماد في قائمة الشبكة المسموح بها

Python

JavaScript

REST

الجمع بين credential وtransform

استخدام بيانات الاعتماد مع خوادم MCP

Python

JavaScript

REST

استخدام بيانات الاعتماد كمتغيّرات بيئة

Python

JavaScript

REST

إنشاء بيانات اعتماد

رمز حامل مميز

Python

JavaScript

REST

Python

JavaScript

REST

OAuth2

Python

JavaScript

REST

متغيّر البيئة

Python

JavaScript

REST

أرقام التعريف التي يتم إنشاؤها

عرض قائمة ببيانات الاعتماد

Python

JavaScript

REST

الحصول على بيانات اعتماد

Python

JavaScript

REST

تغيير بيانات اعتماد

Python

JavaScript

REST

Python

JavaScript

REST

حذف بيانات اعتماد

Python

JavaScript

REST

مرجع الحقل

الأخطاء

الخطوات التالية

الجمع بين `credential` و`transform`