API açarları və mühit dəyişənləri

Bağlantı demək olar ki, hazırdır. Agent konfiqurasiyanı yığıb, servisin adını yazıb və bir sahədə dayanıb - API key. Servis uzun bir sətir verib və sətrin özündən onu haraya qoymaq lazım olduğu görünmür. Yazışmaya? Kodun yanındakı fayla? Birbaşa konfiqurasiyaya, ki, mütləq işləsin?

Bunu bir model üzərində araşdıraq. Dəyərin harada təyin olunduğuna, onu hansı prosesin aldığına və sirrin özünü göstərmədən hər şeyin tənzimləndiyinə necə əmin olmağa baxacağıq. Model yerli işə salma, MCP bağlantısı və dərc olunmuş tətbiq üçün eynidir - yalnız kimin mühitini tənzimlədiyimiz dəyişir.

Giriş açarı nə verir

Açar sorğunu hesab və ya layihə ilə, eləcə də sizə verilən icazələrlə əlaqələndirir. Servis onun vasitəsilə kimin müraciət etdiyini, bu şəxsə nəyə icazə verildiyini və onun artıq nə qədər sorğu göndərdiyini başa düşür. Açarın dəqiq mənasını konkret servis müəyyən edir. Bir yerdə bu, bütün hesaba girişdir, başqa yerdə isə yalnız bir layihəyə və yalnız oxumaq üçün.

Təlimatlarda "açar" sözünün yanında tez-tez token sözünə rast gəlinir. Gündəlik mətnlərdə onları çox vaxt eyni şey kimi işlədirlər, amma mexanizmin detalları fərqlənir. Bunlar alınma üsulu, qüvvədə olma müddəti və icazələr toplusudur. Onları tam sinonim saymamaq daha yaxşıdır - servisin məhz nə verdiyi onun sənədlərində yazılıb.

Servisin sizi ümumiyyətlə nə üçün başqalarından ayırmalı olduğunu gündəlik bir nümunədə görmək daha asandır. Siz hesab açdınız, aylıq sorğu limiti olan tarif seçdiniz və açar aldınız. Sonra servis bu açara görə sorğularınızı sayır, onları limitlə tutuşdurur və tarif ödənişlidirsə, ödəniş üçün hesab çıxarır. Açar kənar adamların əlinə keçibsə, deməli, sizin limitiniz və ödənişiniz hesabına başqası işləyir.

Açar qərarı özü vermir. O, servisə sahibin tənzimləmələrinə istinad verir, konkret sorğuya icazə verilib-verilmədiyini və onun limitdən çıxılıb-çıxılmayacağını isə artıq servis həll edir.

Servisin xüsusi olaraq ictimai kimi qeyd etdiyi dəyərlər də olur - onları məhz səhifənin koduna qoymaq lazımdır. İctimai dəyəri gizli dəyərdən dəyişənin adına görə ayırmaq olmaz. Təyinatı sənədlərdə yazılıb, ora baxmaq lazımdır. Aşağıdakı nümunələrdə hər yerdə fc-EXAMPLE-0000000000 kimi aşkar yer tutucular durur, əsl açar belə görünmür.

Tətbiq sirri harada saxlaya bilər

Belə bir vəziyyət təsəvvür edin. Açarı birbaşa səhifə koduna əlavə etdiniz, layihəni işə saldınız və API-dən cavab aldınız. Hər şey işləyir. Dərc edildikdən sonra tətbiq də açılır, sorğular keçir - tapşırıq həll olundu kimi görünür.

Amma kodla birlikdə hər ziyarətçinin brauzeri açarı da alır. Tərtibatçı alətlərini açmaq, açarı JavaScript-də və ya sorğuda tapıb kopyalamaq kifayətdir. Bundan sonra həmin şəxs sizin adınızdan öz sorğularını göndərə bilər. Onlar sizin limitinizi xərcləyəcək, ta ki servis artıq sizin öz sorğularınızı rədd etməyə başlayana qədər.

Problem konkret yığma alətində deyil. Səhifənin brauzerə ötürdüyü hər şey brauzerin sahibinə açıqdır: HTML, stillər, JavaScript, sorğuların ünvanları və başlıqları. Hətta yığma zamanı açar yerli .env-dən götürülübsə belə, JavaScript-ə yerləşdirildikdən sonra o, qalan kodla birlikdə ziyarətçiyə gedib.

Backend - serverdə işləyən koddur. Ziyarətçi onun cavablarını alır, amma mənbə kodunu və server prosesinin mühit dəyişənlərini almır. Buna görə backend açarı özündə saxlaya və xarici servisə tətbiqin adından müraciət edə bilər.

Sorğu sxemi dəyişir. Brauzer sizin backend-ə gizli açarsız adi sorğu göndərir. Backend açarı öz mühitindən oxuyur, onu API-yə gedən ayrıca sorğuya əlavə edir və brauzerə yalnız nəticəni qaytarır.

İndi ziyarətçi backend-in ünvanını və cavab məlumatlarını görür, amma xarici servisin açarını görmür. Sirr ondan istifadə edən prosesdə qalır.

Sirrin iki mümkün sahibi var:

• yerli proses - inteqrasiya qoşulmuş Claude Code, skript və ya dev-server. O, sizin kompüterinizdə işə düşür və açarı da orada alır;
• dərc olunmuş tətbiqin backend-i - xarici API-yə özü müraciət edən, serverdəki kod. Onun mühitini hostinq panelində tənzimləyirlər.

Bunlar iki ayrı tənzimləmədir. Kompüterinizin mühitindəki açar hostinqdə öz-özünə yaranmayacaq, hətta servis və dəyişənin adı eyni olsa belə.

Açarı backend-ə köçürmək onu brauzerdən gizlədir, amma ictimai backend-i yenə də kənar sorğulardan qorumaq lazımdır.

Mühit dəyişəni necə işləyir

Mühit dəyişəni - proqramın işə düşərkən aldığı adlı dəyərdir. Onun adı var, məsələn FIRECRAWL_API_KEY, və dəyəri var, həmin uzun sətir. Konfiqurasiyalarda və kodda adı yazırlar; dəyər ayrıca yaşayır və kodun yanında saxlanılmır.

Proqram onu haradan götürür? Terminaldan işə salınan proqram həmin terminalın mühitini miras alır. Pəncərədə dəyişəni təyin etdiniz, Claude Code-u da oradan işə saldınız - Claude Code onu görür. İkinci pəncərəni açıb dəyişəni orada təyin etdiniz - artıq işləyən prosesə bunun təsiri yoxdur, mühit ona başlanğıcda verilib.

"Açar ki təyin olunub, amma işləmir" şikayətinin ən çox rast gəlinən səbəbi buradandır. Dəyər başqa pəncərədə və ya işə salmadan sonra təyin olunub. Həlli prosesi dəyişənin olduğu terminaldan yenidən işə salmaqdır.

Tədris variantı, açıq-aşkar saxta dəyərlə:

# bash: indiki terminal üçün dəyişən
export FIRECRAWL_API_KEY=fc-EXAMPLE-0000000000

# PowerShell: eyni şey
$env:FIRECRAWL_API_KEY = "fc-EXAMPLE-0000000000"

Tədris nümunəsində yer tutucu ilə belə yazmaq olar. Əsl açarı bu üsulla yığmaq lazım deyil. Sətir bütövlükdə əmrlər tarixçəsinə düşəcək və siz terminalı bağladıqdan sonra da orada qalacaq. Əsl dəyər üçün ekranda əks olunmayan giriş var - siz sətri yapışdırırsınız, ekranda heç nə görünmür, tarixçəyə isə yalnız əmrin özü düşür:

# bash: dəyər gizli daxil edilir
read -s -r FIRECRAWL_API_KEY
export FIRECRAWL_API_KEY

# PowerShell: gizli giriş və dəyərin açılıb mühit dəyişəninə yazılması
$secure = Read-Host "FIRECRAWL_API_KEY" -AsSecureString
$env:FIRECRAWL_API_KEY = [System.Net.NetworkCredential]::new('', $secure).Password

Tənzimləməni elə yoxlamaq lazımdır ki, dəyər ekrana, loqa və ya ekran şəklinə düşməsin. "Tənzimlənib, ya yox" sualına cavab üçün iki sətir kifayətdir:

# bash
[ -n "$FIRECRAWL_API_KEY" ] && echo "təyin olunub" || echo "təyin olunmayıb"

# PowerShell
if ($env:FIRECRAWL_API_KEY) { "təyin olunub" } else { "təyin olunmayıb" }

Nə uzunluğu, nə də ilk simvolları çap etmək lazım deyil. Yoxlamaya bunun heç bir faydası yoxdur, açarın bir hissəsi isə artıq sirrin bir parçasıdır.

Dəyişəni daimi təyin etməyin yolları çoxdur və hər sistemdə özününküdür. İndi onlarla məşğul olmaq lazım deyil: yerli iş üçün terminal kifayətdir, hostinqdə isə dəyişənləri onun öz panelində təyin edirlər.

.env və .env.example nə üçün lazımdır

Hər yeni terminalda dəyişənləri əllə təyin etmək tez bezdirir, ona görə də dəyərləri .env mətn faylına yığırlar. Oradakı bir sətir bir ad-dəyər cütünü saxlayır.

Ən çox vacib bir detalı nəzərdən qaçırırlar. Faylın özü heç nəyi tənzimləmir. Kimsə onu oxumalı və dəyərləri prosesin mühitinə paylamalıdır - tətbiq, kitabxana və ya proqramınızı işə salan launcher. .env yaradıb indi istənilən proqramın onu götürəcəyini düşünmək olmaz. Sizin halınızda faylı məhz nəyin yüklədiyini fərz etmək yox, birbaşa aydınlaşdırmaq lazımdır.

Onun yanında adətən daha iki fayl olur:

# .env - yalnız kompüterinizdə qalır
FIRECRAWL_API_KEY=fc-EXAMPLE-0000000000

# .env.example - layihəni açacaq şəxs üçün şablon
# dəyərlər boşdur, burada yalnız adlar var
FIRECRAWL_API_KEY=

# .gitignore
.env

Bu bölgünün mənası sadədir. .env.example "bu layihəyə hansı dəyişənlər lazımdır" sualına cavab verir və repozitoriyada rahatca saxlanılır, çünki onda dəyər yoxdur. Əsl açarları ora hətta müvəqqəti olaraq da köçürmürlər.

Git ilə hələ tanış deyilsinizsə, burada .gitignore-un rolunu yadda saxlamaq kifayətdir. O, repozitoriyaya əlavə edilməməli olan faylları sadalayır. Git ilə işi və .gitignore-u ətraflı şəkildə səviyyə 13-də araşdıracağıq.

İndi isə .gitignore ilə bağlı, müntəzəm olaraq rast gəlinən tələ. Qayda yalnız Git-in hələ izləmədiyi fayllara təsir edir. Əgər .env nə vaxtsa commit olunubsa, .gitignore-a sətir əlavə etmək onu izləmədən çıxarmayacaq. Fayl versiya nəzarəti altında qalacaq və onun dəyişiklikləri commit-lərə düşməyə davam edəcək. Git sənədlərində bu, açıq şəkildə deyilir. Git-in artıq izlədiyi fayllara ignore qaydaları təsir etmir. gitignore sənədləri.

Sxemdə əsas şərt ortadadır. .gitignore-dakı eyni sətir yalnız .env izlənmədiyi müddətdə kömək edir. Artıq izlənən fayl üçün ayrıca addım lazımdır.

Ona görə də fayla əsl sirri yazmazdan əvvəl Git-in ondan xəbərsiz olduğuna əmin olmaq yaxşıdır. git status faylın dəyişikliklərə düşüb-düşmədiyini göstərəcək. Fayl artıq izlənirsə, onu git rm --cached .env əmri ilə izləmədən çıxarırlar və bu dəyişikliyi commit edirlər - fayl diskdə qalacaq, amma versiya nəzarətindən çıxacaq.

Sadəcə nəzərə alın ki, bu, gələcək commit-lərə təsir edir. Artıq tarixçəyə düşmüş dəyər orada qalacaq və onunla başqa cür məşğul olmaq lazımdır - bu barədə aşağıda.

Açarı MCP bağlantısına necə ötürmək olar

MCP xarici aləti Claude Code-a qoşmaq üsuludur. Bağlantı .mcp.json faylında təsvir olunur və bu fayl adətən repozitoriyada layihənin yanında durur, yəni onu bütün komanda görür. Deməli, orada sirr olmamalıdır.

Firecrawl servisinin HTTP üzərindən minimal bağlantısı belə görünür:

{
  "mcpServers": {
    "firecrawl": {
      "type": "http",
      "url": "https://mcp.firecrawl.dev/v2/mcp",
      "headers": {
        "Authorization": "Bearer ${FIRECRAWL_API_KEY}"
      }
    }
  }
}

Faylda açar yoxdur. Başlıqda ${FIRECRAWL_API_KEY} durur - mühit dəyişəninə adı ilə istinad. Claude Code bura özünün işlədiyi prosesin mühitindən dəyəri qoyur. Repozitoriyaya ad gedir, dəyər isə hər kəsdə özününkü qalır. Claude Code belə əvəzetməni url, headers, env, command və args sahələrində edə bilir. Claude Code və MCP.

Sxemdən görünür ki, sorğunun başlığında müxtəlif yerlərdən gələn iki şey birləşir. Başlığın şablonu ümumi konfiqurasiyadan gəlir, dəyər isə prosesin mühitindən qoyulur. Heç bir addımda açar repozitoriyaya gedən fayla yazılmır.

Ünvanı və açarın ötürülmə üsulunu servisin öz sənədlərindən götürürlər. Firecrawl-da bu, Authorization başlığıdır və sənədlər ayrıca xahiş edir ki, açarı MCP ünvanına yerləşdirməyəsiniz. Səbəbi sadədir. Ünvan adi mətndir, o, konfiqurasiyaya, loqlara və əmrlər tarixçəsinə düşür, onunla birlikdə ora açar da düşəcək.

Bəzi servislər brauzer vasitəsilə girişi dəstəkləyir. Müştəri giriş səhifəsini özü açır və API key-i əllə ötürmək ümumiyyətlə lazım olmur. Firecrawl-da bunun üçün ayrıca ünvan nəzərdə tutulub. Firecrawl-un MCP sənədləri.

Alət cavab vermirsə, bunları ardıcıllıqla yoxlayın:

1. konfiqurasiyadakı dəyişən adı ilə sizin təyin etdiyiniz ad son simvoluna qədər üst-üstə düşür;
2. dəyər Claude Code-un işə salındığı prosesdə təyin olunub;
3. dəyişən təyin olunduqdan sonra proses yenidən işə salınıb.

Dəyişən olmadıqda Claude Code səssizcə çökmür. O, konfiqurasiyanı yükləyir, ${FIRECRAWL_API_KEY} mətnini əvəz olunmamış saxlayır və çatışmayan dəyişənin adı ilə xəbərdarlıq yazır. Dəyərin özü heç yerdə çap olunmur, ona görə də belə diaqnostika təhlükəsizdir. Problemi tapmaq üçün bütün mühiti çap etməyə isə qətiyyən ehtiyac yoxdur.

Açar artıq kənara çıxıbsa

Vəziyyət adidir. Açar mesajda, commit-də və ya ekran şəklində görünüb. Panikaya düşməyə səbəb yoxdur, amma işi təxirə salmaq da olmaz. Addımların sırası belədir:

1. servisin şəxsi kabinetində açarı ləğv etmək və ya dəyişdirmək. Köhnə sətrin artıq heç nəyi açmaması üçün yeganə addım budur;
2. yeni dəyəri lazım olan yerlərdə təyin etmək: yerli olaraq, hostinqdə, bağlantı tənzimləmələrində;
3. açarın dərc olunduğu yerlə məşğul olmaq - mesajı silmək, faylı düzəltmək, girişi bağlamaq;
4. kabinetdə açarın necə istifadə olunduğuna və servisin xərclər üzrə nə göstərdiyinə baxmaq.

Sıra məhz belədir və birinci addımın yeri dəyişmir. Silinmiş mesaj və ya köhnənin üstündən yeni commit əvvəlki sirri təhlükəsiz etmir. Mesajı oxuya, repozitoriyanı klonlaya, tarixçəni saxlaya bilərdilər. Açar qüvvədə olduğu müddətcə o, onu əlində saxlayan hər kəs üçün işləyir.

Repozitoriya haqqında ayrıca. Sirr commit-ə düşübsə, GitHub-da belə məlumatların silinməsi üzrə təlimat var. Həssas məlumatların repozitoriyadan silinməsi. Sadəcə nəzərə alın ki, tarixçənin tam təmizlənməsi artıq mövcud commit-ləri yenidən yazır, deməli, bu repozitoriya ilə işləyən hər kəsə toxunur. Belə əməliyyatı sahiblərlə razılaşdırırlar, tədris məqaləsinə əsasən təkbaşına işə salmırlar. Açarın dəyişdirilməsi isə dərhal edilir və heç kimlə razılaşdırılmır.

Claude Code-a nəyi tapşırmaq olar

Agent bu məqalədəki mexanikanın demək olar ki, hamısını öz üzərinə götürür, bir şeydən başqa. Sirrin özünü siz daxil edirsiniz. Ona bunları tapşırmaq məntiqlidir:

• konfiqurasiyanı dəyərlə deyil, dəyişənin adı ilə hazırlamaq;
• dəyişəni prosesə məhz nəyin yüklədiyini və o dəyişənin hansı prosesdə olmalı olduğunu adlandırmaq;
• sirrin müştəri yığımında və Git-in izlədiyi fayllarda olmadığını yoxlamaq;
• giriş yoxlamasını icra etmək və dəyəri çıxarmadan nəticə barədə hesabat vermək.

Əsl açarı bunun üçün nəzərdə tutulmuş mexanizm vasitəsilə daxil etmək sizin üzərinizdə qalır: terminalda gizli giriş, yerli fayl, hostinq paneli. Sirr heç vaxt yazışmaya, ekran şəklinə və ya agentin hesabatına düşmür, hətta "bir saniyəlik, yoxlamaq üçün" də.

Tapşırıq təxminən belə səslənə bilər:

Servisi API vasitəsilə qoş. Açarı özüm təyin edəcəyəm.
Sənədlərdən ünvanı, metodu və açarın ötürülmə üsulunu götür.
Konfiqurasiyaya dəyəri yox, mühit dəyişəninin adını yaz.
De ki, dəyişəni hansı proses almalıdır və onu nə yükləyir.
Açarın müştəri yığımında və Git-in izlədiyi fayllarda olmadığını yoxla.
Giriş yoxlamasını dəyəri və onun hissələrini çıxarmadan et.
Nəticəni bildir: tənzimlənib, təyin olunmayıb və ya giriş rədd edilib.

Və sonuncu, hesabatı oxumaq haqqında. "Dəyişən təyin olunub" və "giriş işləyir" fərqli iddialardır, birini digəri ilə əvəz etmək olmaz. Dəyərin olmaması da servisin imtinasından fərqlənir. Birinci halda sorğunu imzalamağa heç nə yoxdur, ikincidə servis cavab verib, amma giriş verməyib. Agent sadəcə "hazırdır" deyirsə, məhz nəyi yoxladığını dəqiqləşdirin.