Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Cruthaigh agus cumraigh eochair API

Ceacht 2 as 14 Nuashonraithe 29 Iúil 2026 Forbróir
Ar an leathanach seo
  1. Cén fáth eochracha a chruthú tríd an API
  2. Críochphointe cruthaithe
  3. Sampla iomlán le curl
  4. Straitéisí ACL molta
  5. Críochphointí ACL atá ar fáil
  6. Príomhphointí

Cén fáth eochracha a chruthú tríd an API

Tógann sé tríocha soicind eochair a chruthú de láimh—sin díreach an fáth a bhfuil uathoibriú ag teastáil uait. Toisc go bhfuil sé tapa, déanann tú é gan smaoineamh: gan coinbhinsiún ainmniúcháin, gan teorainneacha ráta, ach cárta fiáin “chun bogadh go tapa”. Sé mhí ina dhiaidh sin, níl a fhios ag aon duine céard a dhéanann gach eochair.

Cuireann úsáid an API iallach ort gach eochair a ainmniú, a scópú agus a theorannú toisc gur paraiméadair scripte iad seo. Ní disciplín atá le cothabháil a thuilleadh é an comhsheasmhacht, ach airí den chód. Is féidir leat cruthú eochracha a uathoibriú do do thimpeallachtaí (forbairt, stáitsiún, táirgeadh), ACLanna gráinneacha a chur i bhfeidhm, agus teorainneacha ráta a shainiú—go léir laistigh de do scripteanna imlonnaithe nó d’uirlisí bonneagair.

Críochphointe cruthaithe

Chun eochair API a chruthú, seol iarratas POST chuig an gcríochphointe seo a leanas:

POST /auth/teams/{teamId}/api-keys

Corp an iarratais

{
  "name": "ma-cle-production",
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 10,
  "qpm": 100,
  "tpm": 1000000,
  "expireTime": "2026-12-31T23:59:59Z"
}

Paraiméadair mhionsonraithe

name (riachtanach): aitheantóir inléite do d’eochair. Roghnaigh ainm cur síosach a léiríonn an úsáid (prod-backend, staging-chatbot, dev-john). Feictear an t-ainm seo sa chonsól agus i logaí úsáide.

acls (riachtanach): an liosta ceadanna a dheonaítear don eochair seo. Tá dhá fhormáid ar fáil:

  • api-key:endpoint:[endpoint] — teorannaíonn sé na críochphointe inrochtana (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[model] — teorannaíonn sé na samhlacha inúsáidte (grok-4.20-0309-reasoning, grok-4.3, srl.)

Feidhmíonn an carachtar * mar chárta fiáin: údaróidh api-key:endpoint:* gach críochphointe, agus api-key:model:* gach samhail. Coinnigh é seo d’fhorbairt áitiúil. Sa táirgeadh, ciallaíonn cárta fiáin go dtugann eochair atá curtha i mbaol rochtain ar gach rud is féidir le do fhoireann a dhéanamh—including na samhlacha is costasaí, nach bhféadfadh d’iarratas a úsáid riamh.

qps (roghnach): ceisteanna in aghaidh an tsoicind — uasmhéid iarratas in aghaidh an tsoicind.

qpm (roghnach): ceisteanna in aghaidh an nóiméid — uasmhéid iarratas in aghaidh an nóiméid.

tpm (roghnach): tokenanna in aghaidh an nóiméid — uasmhéid tokenanna próiseáilte in aghaidh an nóiméid.

expireTime (roghnach): dáta éaga i bhformáid ISO 8601. Díchumasófar an eochair go huathoibríoch ar an dáta seo.

Sampla iomlán le curl

curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v2",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning",
      "api-key:model:grok-4.3"
    ],
    "qps": 20,
    "qpm": 500,
    "tpm": 2000000,
    "expireTime": "2027-06-30T23:59:59Z"
  }'

Tá an eochair rúnda sa fhreagra, agus ní thaispeánfar arís í riamh. Tá toradh praiticiúil ag an riail seo nach mór duit a réamh-mheas sula rithfidh tú an script, ní ina dhiaidh: má chruthaíonn tú eochracha i lúb, caithfidh an stóráil tarlú san ghluaiseacht chéanna. Ní féidir eochair a chailltear idir cruthú agus clárú a fháil ar ais—caithfidh tú í a scriosadh agus tosú arís. Scríobh í chuig stór (Vault, AWS Secrets Manager) seachas aschur caighdeánach do theirminéil, áit a mbeidh sí i do stair.

Straitéisí ACL molta

Eochair forbartha (leathan)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 5,
  "qpm": 50
}

Idealach d’fhorbairt áitiúil: tá an rochtain leathan toisc nach bhfuil a fhios agat roimh ré cad a dhéanfaidh tú a thriail, ach fanann na teorainneacha ráta íseal. Seo an comhréiteach ceart—costóidh lúb gan chríoch a scríobhadh de thaiste oíche Aoine cúpla cent seachas cúpla céad euro.

Eochair táirgeachta (srianta)

{
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 50,
  "qpm": 2000,
  "tpm": 5000000
}

Sa táirgeadh, casann an riail bun os cionn: tosaigh ón méid a dhéanann an t-iarratas i ndáiríre agus údarú ach é sin. Is é an cheist le cur nuair a scríobhann tú an ACL ná an cheist chéanna i gcónaí—dá sceitheadh an eochair seo amárach, cad is féidir le tríú páirtí a dhéanamh leis? Tugann eochair atá teoranta do chat ar shamhail amháin agus teoranta do dheich n-iarratas in aghaidh an tsoicind freagra gairid.

Eochair shealadach (inchurtha in éag)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "expireTime": "2026-04-10T00:00:00Z"
}

Réitíonn éag uathoibríoch an fhadhb nach mbíonn aon duine in ann a láimhseáil: eochracha a dhéanann daoine dearmad a scriosadh. POC, léiriú, conraitheoir sealadach—i ngach cás seo, ráthaíonn expireTime go múchfar an rochtain léi féin. Seo an t-aon bhealach iontaofa chun fardal glan a choinneáil, toisc nach mbraitheann sé ar chuimhne aon duine.

Críochphointí ACL atá ar fáil

Chun na críochphointe is féidir leat a úsáid in ACLanna a fheiceáil, féach ar:

GET /auth/teams/{teamId}/endpoints

Is iad na críochphointe atá ar fáil ná: chat, embed, image, models, sample, tokenize, documents. D’fhéadfadh an liosta seo athrú le himeacht ama, mar sin seiceáil go rialta.

Príomhphointí

  • Tarlaíonn cruthú eochracha trí POST /auth/teams/{teamId}/api-keys
  • Leanann ACLanna an fhormáid api-key:endpoint:[name] nó api-key:model:[name]
  • Tugann an cárta fiáin * rochtain iomlán ar gach críochphointe nó samhail
  • Taispeántar an eochair rúnda uair amháin ag an am cruthaithe—sábháil í láithreach
  • Sainigh teorainneacha ráta (qps, qpm, tpm) atá oiriúnach don úsáid i gcónaí
  • Úsáid expireTime d’eochracha sealadacha