اعتبارنامهها اسرار مدیریتشده توسط سرور هستند که به نمایندگان شما امکان میدهند بدون اینکه این اسرار وارد محیط نماینده شود، به سرویسهای طرف سوم دسترسی پیدا کنند. اطلاعات اعتباری را یکبار ذخیره میکنید، با شناسه به آن ارجاع میدهید، و پراکسی خروجی آن را در زمان درخواست حل و تزریق میکند.
مقادیر رمز فقط نوشتنی هستند. پساز ذخیره شدن، هیچگاه توسط هیچ پایانی برگردانده نمیشوند، بنابراین کارگزار درمعرض خطر نمیتواند نشانهایی را که استفاده میکند بازخوانی کند.
مکان اصلی که از اطلاعات اعتباری استفاده میکنید فهرست مجاز شبکه در
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}`);
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
Body: credentials.NewCredentialCreateParams(credentials.HTTPBearerConfig{
ID: "github-production",
Token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Credential ID: %s, Status: %v\n", res.Credential.ID, res.Credential.GetStatus())
}
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: "*" },
],
},
},
});
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Triage the open issues in my-org/my-repo."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
{Domain: "api.github.com", Credential: genai.Ptr("github-production")},
{Domain: "*"},
})),
})),
})),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Interaction.GetOutputText())
}
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 |
کدهای دسترسی شخصی، کدهای روبات، کلیدهای API ثابت | کارگزار وکالتی کد را بهعنوان سرایند درخواست تزریق میکند. منطق بازآوری وجود ندارد. |
oauth2 |
برنامههای OAuth و جریانهای واگذارشده کاربر | کارگزار جانشین، کد بازآوری را با کدهای دسترسی مبادله میکند و آنها را با انقضایشان بازآوری میکند. |
environment_variable |
کیتهای توسعه نرمافزار کارخواهی که رمزها را از محیط فرایند میخوانند | محیط کارگزار جایبانی دریافت میکند. کارگزار جانشین رمز واقعی در درخواستهای خروجی میشود. |
استفاده از اعتبارنامهها در فهرست مجاز شبکه
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" },
],
},
},
});
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Sync the open Jira issues into the tracking sheet in my repo."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
Sources: []interactions.Source{
{
Type: interactions.SourceTypeRepository.ToPointer(),
Source: genai.Ptr("https://github.com/your-org/backend"),
Target: genai.Ptr("/backend-app"),
},
},
Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
{Domain: "github.com", Credential: genai.Ptr("github-production")},
{Domain: "api.atlassian.com", Credential: genai.Ptr("jira-oauth")},
{Domain: "*.googleapis.com"},
})),
})),
})),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Interaction.GetOutputText())
}
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",
}],
});
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Create a new issue in my-org/my-repo"),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
{Domain: "api.githubcopilot.com", Credential: genai.Ptr("github-production")},
})),
})),
})),
Tools: []interactions.Tool{
interactions.NewTool(interactions.MCPServer{
Name: genai.Ptr("github"),
URL: genai.Ptr("https://api.githubcopilot.com/mcp"),
}),
},
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Interaction.GetOutputText())
}
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 جایگزین کنید.
سایر سرایندها را در جای خود نگه دارید.
استفاده از اطلاعات اعتباری بهعنوان متغیرهای محیط
برخیاز کتابخانههای مشتری رمزها را از محیط فرایند میخوانند نه اینکه آنها را بهعنوان سرصفحههای درخواست بپذیرند. کاربران حالت سوکت و نظرسنجی طولانی حالت رایج هستند.
اطلاعات اعتباری 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" },
},
},
});
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Run the sync script and check notifications."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
Env: genai.Ptr(interactions.NewEnv(map[string]interactions.EnvVar{
"NODE_ENV": {Value: genai.Ptr("production")},
"SLACK_BOT_TOKEN": {Credential: genai.Ptr("slack-bot-token")},
})),
})),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Interaction.GetOutputText())
}
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",
});
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
Body: credentials.NewCredentialCreateParams(credentials.HTTPBearerConfig{
ID: "github-production",
Token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created credential: %s\n", res.Credential.ID)
}
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: "",
});
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
Body: credentials.NewCredentialCreateParams(credentials.HTTPBearerConfig{
ID: "my-api-key",
Token: "key_xxxxxxxxxxxx",
HeaderName: genai.Ptr("x-goog-api-key"),
Prefix: genai.Ptr(""),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created credential: %s\n", res.Credential.ID)
}
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"],
});
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
Body: credentials.NewCredentialCreateParams(credentials.OAuth2Config{
ID: "jira-oauth",
ClientID: "my-client-id",
ClientSecret: "my-client-secret",
TokenURL: "https://auth.atlassian.com/oauth/token",
RefreshToken: "rt_xxxxxxxxxxxxxxxxxxxx",
Scopes: []string{"read:jira-work", "write:jira-work"},
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created OAuth2 credential: %s\n", res.Credential.ID)
}
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",
});
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
Body: credentials.NewCredentialCreateParams(credentials.EnvironmentVariableConfig{
ID: "slack-bot-token",
Value: "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
TrustedDomains: []string{"*.slack.com", "slack.com"},
InjectionLocation: credentials.NewEnvironmentVariableConfigInjectionLocation(credentials.InjectionLocationEnumHeader),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created environment variable credential: %s\n", res.Credential.ID)
}
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 اختیاری است. آن را حذف کنید و سرویس یک 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"
}
وقتی میخواهید مرجع پایدار و خوانایی برای استفاده در تعاملات داشته باشید، شناسه خودتان را ارائه دهید. ازآنجاییکه شناسه در مسیر منبع نشان داده میشود، حروف الفباعددی کوچک با خط تیره یا زیرخط را ترجیح دهید.
فهرست اعتبارنامهها
اعتبارنامههای متعلق به پروژهتان را فهرست کنید. از پارامترهای صفحهبندی برای کنترل اندازه دستهای پاسخ استفاده کنید.
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}`);
}
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.List(ctx, operations.ListCredentialsRequest{
PageSize: genai.Ptr(10),
})
if err != nil {
log.Fatal(err)
}
for _, cred := range res.CredentialListResponse.Credentials {
fmt.Printf("Credential ID: %s, Type: %v\n", cred.ID, cred.GetType())
}
}
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}`);
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Get(ctx, operations.GetCredentialRequest{
ID: "github-production",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Credential ID: %s, Status: %v\n", res.Credential.ID, res.Credential.GetStatus())
}
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",
});
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Update(ctx, operations.UpdateCredentialRequest{
ID: "github-production",
Body: credentials.NewCredentialUpdate(credentials.HTTPBearerUpdateConfig{
Token: genai.Ptr("ghp_new_xxxxxxxxxxxxxxxxxxxx"),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Updated credential %s at %v\n", res.Credential.ID, res.Credential.GetUpdateTime())
}
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",
});
رفتن
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Update(ctx, operations.UpdateCredentialRequest{
ID: "jira-oauth",
Body: credentials.NewCredentialUpdate(credentials.OAuth2UpdateConfig{
RefreshToken: genai.Ptr("rt_new_xxxxxxxxxxxxxxxxxxxx"),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Updated credential %s at %v\n", res.Credential.ID, res.Credential.GetUpdateTime())
}
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");
رفتن
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
_, err = client.Credentials.Delete(ctx, operations.DeleteCredentialRequest{
ID: "github-production",
})
if err != nil {
log.Fatal(err)
}
}
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 |
رشته | نه | سرایندی که باید تزریق شود. پیشفرض 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 ناموفق بود. |
| 404 | not_found |
اطلاعات اعتباری با این شناسه وجود ندارد. |
| 409 | aborted |
اطلاعات اعتباری با این شناسه ازقبل وجود دارد. |
فیلدهای ناشناخته بهجای نادیده گرفته شدن رد میشوند و خطا نام فیلد را ذکر میکند:
{
"error": {
"message": "Unknown parameter 'headerName'. Did you mean 'header_name'?",
"code": "invalid_request"
}
}
قدم بعدی چیست
- محیطها: با نحوه اجرای کد و ماندگاری فایلها توسط عاملها آشنا شوید.
- نمای کلی عاملها: با مفاهیم اصلی عاملهای مدیریتشده آشنا شوید.
- ساختن عاملهای سفارشی: بااستفاده از
AGENTS.mdوSKILL.md، عاملهای خودتان را تعریف کنید.