CLI-kimenetek és hibaelhárítás
A CLI egyetlen JSON-dokumentumot ír a szabványos kimenetre. Mielőtt valódi postafiókot használsz, végezd el a beállítást.
JSON-eredmények
Egy sikeres módosítás ilyen eredményt adhat:
{"status":"Moved","emailId":"immutable-message-id","targetId":"folder-id"}
Egy sikeres olvasás ilyen eredményt adhat:
{"status":"Listed","labels":[{"labelId":"category-id","labelColor":"preset4","labelName":"Important"}]}
Egy hiba ilyen eredményt adhat:
{"status":"Errored","operation":"email.move","errorReason":"The message was not found.","graphCode":"ErrorItemNotFound","graphStatusCode":404}
A hibában szerepelhet requestId, ha a Microsoft megadja. Szolgáltatói incidensjelentésben add meg, de hitelesítő adatot ne ossz meg.
Kilépési kódok
| Kód | Jelentés | Példák |
|---|---|---|
0 | Sikeres vagy változatlan, idempotens eredmény | Listed, Sent, Moved, Added, Removed, Unchanged |
1 | Minden olyan hiba, amely nem CliValidationError | Szolgáltatói és futásidejű hibák, valamint egyes bemeneti vagy elemzési hibák |
2 | CliValidationError | Ellenőrzött hiányzó kapcsoló, érvénytelen prioritás, vagy hiányzó konfiguráció azokon az útvonalakon, amelyek ezt a hibatípust használják |
A user lookup, az email get, az attachments, a reply, a reply-all és a forward egy újabb parancsútvonalat használ. Ott a hiányzó vagy érvénytelen argumentumok sima hibát vagy argumentum-elemzési hibát dobhatnak, és 1 kilépési kódot adnak. Ezért nem minden bemeneti hiba ad 2 kódot, és nem minden 1 jelent szolgáltatói hibát.
Az automatizálásnak sikeres mezők feldolgozása előtt 0 kilépési kódot kell követelnie. Nem nulla kilépési kód esetén nézd meg a Errored eredményt. Ne válassz újrapróbálást csak az 1 kód alapján. Egy küldési hiba is igényelheti az elküldött elemek ellenőrzését.
Sikeres mező feldolgozása előtt ellenőrizd a kilépési állapotot:
bun run cli -- label list --user-id person@example.com
result=$?
if [ "$result" -ne 0 ]; then
echo "Graph CLI failed with exit code $result"
fi
Állapotértékek
| Állapot | Jelentés |
|---|---|
Listed | A listázás befejeződött |
Found | Az erőforrás lekérése befejeződött |
Created | Mappa vagy kategória létrehozva |
Updated | Mappa vagy kategória frissítve |
Sent | Az elküldöttek másolata és az internetes üzenetazonosító megfigyelve |
Arrived | A megfelelő címzetti másolat megtalálva |
Seen | Az üzenet olvasottnak jelölve |
Moved | Üzenet vagy mappa áthelyezve |
Added, Removed | A kategória-tagság megváltozott |
Unchanged | A kért idempotens kategóriaállapot már fennáll |
Deleted | Az üzenet a Törölt elemek mappába került, vagy mappa, illetve kategória törölve |
PermanentlyDeleted | A szolgáltató végleges törlési művelete befejeződött |
Errored | A művelet sikertelen |
A Sent a feladói oldali megfigyelés. Nem bizonyítja a címzett kézbesítését. Az Arrived külön eredmény.
Visszafordíthatatlan parancsok
Az email permanent-delete, a folder delete és a label delete parancsokhoz --confirm kell. Ez engedélyezi a valódi módosítást vagy törlést. Az email delete nem kér megerősítést, mert ez a parancs az üzenetet a Törölt elemek mappába helyezi. A végleges törlés a Törölt elemek mappában lévő, jogosult üzenetet igényel.
Hibák diagnosztizálása
Hiányzó környezeti változó
A JSON-hiba megnevezi a szükséges változót, például a CLIENT_SECRET értéket. Javítsd a CLI biztonságos konfigurációját a TENANT_ID, CLIENT_ID és CLIENT_SECRET értékekhez. Ne használj más szolgáltatás változóneveit.
401 Unauthorized
Ellenőrizd a lejárt vagy érvénytelen titkot, a bérlő- és kliensazonosságot, és azt, hogy a hitelesítő adat a megfelelő bérlőhöz tartozik-e.
403 Forbidden
Ellenőrizd az alkalmazásjogosultságokat, az adminisztrátori hozzájárulást, az Exchange-alkalmazáshatókört, a védett rendszermappák korlátozásait, valamint a megőrzési és megfelelési szabályokat. Lásd: Graph-beállítás.
404 vagy ErrorItemNotFound
Ellenőrizd az azonosító postafiókbeli tulajdonjogát, a változatlan azonosító formátumát, a postafiókok közötti másolat összetévesztését és a végleges törlést. Címzetti másolatnál futtasd az email wait parancsot a feladó internetMessageId értékével, majd használd a visszaadott emailId értéket.
A mappanév hiányzik vagy kétértelmű
A nevek pontosan, kis- és nagybetű-érzéketlenül egyeznek. A részleges nevek nem egyeznek. Listázd a mappákat:
bun run cli -- folder list --user-id person@example.com
Használd a pontos nevet vagy azonosítót. Különböző hierarchiaágakban ugyanaz a megjelenített név előfordulhat. Kétértelműségi hiba esetén a visszaadott egyező azonosítók láthatók. Válaszd ki explicit módon a kívánt azonosítót.
Hiányzó kategórianév
Listázd a kategóriákat, majd használd a --label-id kapcsolót vagy a pontos megjelenített nevet:
bun run cli -- label list --user-id person@example.com
Küldési megerősítés időtúllépése
A Graph elfogadta a beküldést, de az eszköz 30 másodpercen belül nem látta az elküldöttek másolatát és annak internetMessageId értékét. Az üzenet már elment lehet. Újrapróbálás előtt nézd meg az elküldötteket, hogy elkerüld a duplikációt.
Megérkezési időtúllépés
A kézbesítés túlléphet a --timeout-ms értéken. Ellenőrizd, hogy a címzett cím és a --user-id ugyanazt a postafiókot jelöli-e. Egy szabály vagy karantén átirányíthatja az üzenetet. Egy mappaszűrő el is rejtheti. Növeld az időkorlátot, vagy távolítsd el a mappaszűrőt az eredeti küldés ellenőrzése után.
429 Too Many Requests
Csökkentsd a kérések gyakoriságát, növeld a --poll-interval-ms értéket, és kerüld az ismételt teljes postafiók-listázást. Kövesd a szolgáltató vagy az SDK újrapróbálási útmutatását.
Automatizálás
A mező kinyerése előtt mentsd el a teljes sikeres JSON-t. Így a hibakezelés elválik a jq feldolgozástól:
if result=$(bun run cli -- email send \
--user-id person@example.com \
--to recipient@example.com \
--subject "Automated test" --body "Body" --priority normal); then
email_id=$(printf '%s' "$result" | jq -r '.emailId')
fi
Ez a példa valódi levelet küld. Használj engedélyezett teszt-célpontot.
| Parancsot használj, ha | Munkafolyamatot használj, ha |
|---|---|
| Egy művelet elegendő | Több, egymásra épülő lépés szükséges |
| Az állapotot kézzel vizsgálod | Ismételhető forgatókönyvre van szükséged |
| Egy shell kezeli a köztes állapotot | TypeScript-típusok kötik össze a lépéseket |
| Az azonosítók ismertek | Egy eredmény adja a következő bemenetet |
Lásd: programozott munkafolyamatok.