Gemini 3.8 Flash اکنون در دسترس است. آن را امتحان کنید .

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

اعتبارنامه‌ها در نمایندگان مدیریت‌شده

اعتبارنامه‌ها، اطلاعات محرمانه‌ای هستند که توسط سرور مدیریت می‌شوند و به کارگزاران شما اجازه می‌دهند بدون ورود این اطلاعات محرمانه به محیط کارگزار، به سرویس‌های شخص ثالث دسترسی پیدا کنند. شما یک بار اعتبارنامه را ذخیره می‌کنید، با شناسه به آن ارجاع می‌دهید و پروکسی خروجی آن را در زمان درخواست، پردازش و تزریق می‌کند.

مقادیر مخفی فقط قابل نوشتن هستند. پس از ذخیره شدن، دیگر توسط هیچ نقطه پایانی بازگردانده نمی‌شوند، بنابراین یک عامل آسیب‌دیده نمی‌تواند توکن‌هایی را که استفاده می‌کند، بخواند.

محل اصلی استفاده از اعتبارنامه، فهرست مجوزهای شبکه در environment.network است. ابتدا رمز را ذخیره کنید:

پایتون

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

جاوا اسکریپت

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

استراحت

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"
}'

سپس آن را به دامنه‌ای که احراز هویت می‌کند، متصل کنید:

پایتون

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": "*"},
            ]
        },
    },
)

جاوا اسکریپت

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: "*" },
            ],
        },
    },
});

استراحت

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 ارسال می‌کند، و توکن هرگز در داخل sandbox وجود ندارد.

انواع اعتبارنامه

هر اعتبارنامه یک type دارد که تعیین می‌کند کدام فیلدها را بپذیرد و پروکسی چگونه آن را اعمال کند.

نوع	مورد استفاده	رفتار
`bearer_token`	توکن‌های دسترسی شخصی، توکن‌های ربات، کلیدهای API استاتیک	پروکسی توکن را به عنوان هدر درخواست تزریق می‌کند. بدون منطق رفرش.
`oauth2`	برنامه‌های OAuth و جریان‌های محول‌شده توسط کاربر	پروکسی، توکن به‌روزرسانی را با توکن‌های دسترسی تعویض می‌کند و پس از انقضا، آنها را به‌روزرسانی می‌کند.
`environment_variable`	SDK های کلاینت که اسرار را از محیط فرآیند می‌خوانند	محیط عامل یک متغیر جایگزین دریافت می‌کند. پروکسی در درخواست‌های خروجی، جایگزین رمز اصلی می‌شود.

از اعتبارنامه‌های موجود در فهرست مجاز شبکه استفاده کنید

با اضافه کردن credential به یک قانون لیست مجوز، پروکسی هر درخواست خروجی به آن دامنه را احراز هویت می‌کند. این روش توصیه شده برای دسترسی به یک عامل به یک API خصوصی، یک مخزن خصوصی یا یک سطل خصوصی است.

شما می‌توانید قوانین احراز هویت شده و احراز هویت نشده را در یک لیست مجاز با هم ترکیب کنید:

پایتون

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"},
            ]
        },
    },
)

جاوا اسکریپت

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" },
            ],
        },
    },
});

استراحت

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`

قوانین Allowlist همچنین یک شیء transform درون‌خطی را می‌پذیرند که هدرها را مستقیماً روی قانون تنظیم می‌کند. هر دو مکانیسم توسط پروکسی خروجی روی سیم اعمال می‌شوند، بنابراین در هر دو مورد مقدار هدر هرگز در داخل sandbox وجود ندارد. هر دو فیلد می‌توانند در یک قانون ظاهر شوند.

پیکربندی قوانین	رفتار
فقط `credential`	پروکسی اعتبارنامه را حل می‌کند و هدر آن را در هر درخواست به دامنه تزریق می‌کند.
فقط `transform`	تزریق هدر استاتیک. هدرهایی که می‌نویسید به همان صورت ارسال می‌شوند.
هر دو	ابتدا اعتبارنامه اعمال می‌شود، سپس `transform` روی آن ادغام می‌شود. اگر هر دو کلید یکسانی را تنظیم کنند، یک هدر `transform` صریح برنده می‌شود.
هیچ کدام	دامنه مجاز است و هیچ هدری تزریق نمی‌شود.

استفاده از اعتبارنامه زمانی ارزشمند است که می‌خواهید یک راز را یک بار ذخیره کنید و از هر محیط، عامل و تریگر در پروژه خود به آن ارجاع دهید، و زمانی که می‌خواهید به‌روزرسانی توکن دسترسی و چرخش آن برای شما مدیریت شود. transform درون‌خطی زمانی مناسب است که مقدار متعلق به یک فراخوانی واحد باشد، به عنوان مثال توکنی که خودتان درست قبل از ایجاد تعامل ایجاد می‌کنید.

ترکیب این دو رایج است. اعتبارنامه حاوی هدر احراز هویت است و transform هر چیز دیگری را که سرویس بالادستی در همان درخواست انتظار دارد، اضافه می‌کند:

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

برای انتقال یک راز از یک transform درون‌خطی و به یک اعتبارنامه، آن را با POST /credentials ذخیره کنید، هدر auth را در transform با "credential": "<id>" جایگزین کنید و بقیه شیء transform را دست نخورده باقی بگذارید.

استفاده از اعتبارنامه‌ها با سرورهای MCP

سرورهای MCP از راه دور، فیلد credential یکسانی را دریافت می‌کنند. آن را روی ابزار mcp_server تنظیم کنید و پروکسی، هدر auth را به هر درخواستی که به آن سرور ارسال می‌شود، تزریق می‌کند:

پایتون

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",
    }],
)

جاوا اسکریپت

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",
    }],
});

استراحت

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 ذخیره کنید و ورودی auth را در headers با credential جایگزین کنید. سایر هدرها را در جای خود نگه دارید.

استفاده از اعتبارنامه‌ها به عنوان متغیرهای محیطی

برخی از کتابخانه‌های کلاینت، به جای پذیرش رمزها به عنوان هدر درخواست، آنها را از محیط فرآیند می‌خوانند. کلاینت‌های حالت سوکت و long-polling موارد رایجی هستند.

یک اعتبارنامه environment_variable را به یک نام متغیر در environment.env متصل کنید:

پایتون

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

جاوا اسکریپت

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" },
        },
    },
});

استراحت

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 اعتبارنامه می‌روند، با راز واقعی جایگزین می‌شود. درخواست به هر دامنه دیگری رد می‌شود، بنابراین راز هرگز از محیط خارج نمی‌شود و جای‌نگهدار به جای آن ارسال نمی‌شود.

روی هر اعتبارنامه environment_variable trusted_domains تنظیم کنید. این کنترلی است که محدوده استفاده از رمز را تعیین می‌کند.

ایجاد اعتبارنامه

هر درخواست ایجاد به یک type و به علاوه‌ی فیلدهایی که آن نوع نیاز دارد، نیاز دارد.

هنگام فراخوانی مستقیم REST، نام همه فیلدها از snake_case استفاده می‌کند. ارسال فیلد camelCase مقدار 400 را برمی‌گرداند.

توکن حامل

اعتبارنامه‌ی توکن حامل فقط token نیاز دارد:

پایتون

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

جاوا اسکریپت

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

استراحت

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 را نادیده بگیرید:

پایتون

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

جاوا اسکریپت

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

استراحت

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 اختیاری است:

پایتون

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"],
)

جاوا اسکریپت

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"],
});

استراحت

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 نیاز دارد:

پایتون

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

جاوا اسکریپت

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",
});

استراحت

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 اختیاری است. آن را حذف کنید و سرویس یک UUID تولید می‌کند:

{
  "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"
}

وقتی می‌خواهید یک مرجع پایدار و خوانا برای استفاده در تعاملات مختلف داشته باشید، شناسه خودتان را ارائه دهید. از آنجایی که شناسه در مسیر منبع ظاهر می‌شود، حروف کوچک و عددی را با خط فاصله یا زیرخط ترجیح دهید.

فهرست کردن اعتبارنامه‌ها

اعتبارنامه‌های مربوط به پروژه خود را فهرست کنید. از پارامترهای صفحه‌بندی برای کنترل اندازه دسته پاسخ استفاده کنید.

پایتون

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

جاوا اسکریپت

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

استراحت

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` مربوط به پاسخ قبلی.

دریافت اعتبارنامه

بازیابی فراداده برای یک اعتبارنامه خاص با استفاده از شناسه آن.

پایتون

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

جاوا اسکریپت

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

استراحت

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 و همچنین فیلدهایی باشد که می‌خواهید تغییر دهید. فیلدهایی که حذف می‌کنید، مقادیر فعلی خود را حفظ می‌کنند.

چرخاندن یک توکن حامل:

پایتون

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

جاوا اسکریپت

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

استراحت

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:

پایتون

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

جاوا اسکریپت

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

استراحت

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 یک اعتبارنامه در زمان ایجاد ثابت است. برای تغییر آن، اعتبارنامه را حذف کرده و یک اعتبارنامه جدید ایجاد کنید.

حذف اعتبارنامه

وقتی دیگر نیازی به یک اعتبارنامه و اطلاعات محرمانه‌ی ذخیره‌شده‌اش ندارید، آن را حذف کنید.

پایتون

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

جاوا اسکریپت

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

استراحت

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`	رشته	خیر	هدری که باید تزریق شود. مقدار پیش‌فرض `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`	علت
۴۰۰	`invalid_request`	فیلد الزامی وجود ندارد، فیلد ناشناخته است، `type` پشتیبانی نشده است، یا اعتبارسنجی OAuth2 ناموفق است.
۴۰۴	`not_found`	با اون مدرک شناسایی هیچ مدرکی وجود نداره.
۴۰۹	`aborted`	یک اعتبارنامه با آن شناسه از قبل وجود دارد.

فیلدهای ناشناخته به جای نادیده گرفتن، رد می‌شوند و خطا، فیلد را نامگذاری می‌کند:

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

قدم بعدی چیست؟

محیط‌ها : بیاموزید که چگونه عامل‌ها کد را اجرا می‌کنند و فایل‌ها را ذخیره می‌کنند.
مرور کلی عامل‌ها : با مفاهیم اصلی عامل‌های مدیریت‌شده آشنا شوید.
ساخت عامل‌های سفارشی : عامل‌های خودتان را با استفاده از AGENTS.md و SKILL.md تعریف کنید.

اعتبارنامه‌ها در نمایندگان مدیریت‌شده

پایتون

جاوا اسکریپت

استراحت

پایتون

جاوا اسکریپت

استراحت

انواع اعتبارنامه

از اعتبارنامه‌های موجود در فهرست مجاز شبکه استفاده کنید

پایتون

جاوا اسکریپت

استراحت

ترکیب credential و transform

استفاده از اعتبارنامه‌ها با سرورهای MCP

پایتون

جاوا اسکریپت

استراحت

استفاده از اعتبارنامه‌ها به عنوان متغیرهای محیطی

پایتون

جاوا اسکریپت

استراحت

ایجاد اعتبارنامه

توکن حامل

پایتون

جاوا اسکریپت

استراحت

پایتون

جاوا اسکریپت

استراحت

OAuth2

پایتون

جاوا اسکریپت

استراحت

متغیر محیطی

پایتون

جاوا اسکریپت

استراحت

شناسه‌های تولید شده

فهرست کردن اعتبارنامه‌ها

پایتون

جاوا اسکریپت

استراحت

دریافت اعتبارنامه

پایتون

جاوا اسکریپت

استراحت

چرخاندن یک اعتبارنامه

پایتون

جاوا اسکریپت

استراحت

پایتون

جاوا اسکریپت

استراحت

حذف اعتبارنامه

پایتون

جاوا اسکریپت

استراحت

مرجع میدانی

خطاها

قدم بعدی چیست؟

ترکیب `credential` و `transform`