AMQP autentizace (CZ)

Připojte se přes AMQPS na amqp.voke.turena.cz:5671 s vaším slugem organizace jako uživatelským jménem a vaším plaintext API klíčem jako heslem. Broker vám posílá telemetrii, alarmy a status události; vy zpět přes stejné spojení publikujete příkazy, rozvrhy (schedules) a konfiguraci.

REST protějšek (stejný průvodce, jiný scope) najdete v REST autentizaci.

Jak je spojení tvarováno

Jedno AMQPS URI nese vše, co broker potřebuje. Přečtěte si ho jednou a zbytek průvodce dává smysl:

amqps://<org-slug>:<api-key>@amqp.voke.turena.cz:5671/partner-<key-id>
        └─ username ─┘ └─ password ─┘  └─── host:port ───┘  └── vhost ──┘

• <org-slug> — slug vaší organizace, ten samý, který je ve vaší workspace URL (voke.turena.cz/orgs/<slug>/…).
• <api-key> — plaintext klíč, který si vytvoříte v průvodci níže. Zobrazí se přesně jednou na obrazovce s odhalením.
• amqp.voke.turena.cz:5671 — veřejný AMQPS endpoint Voke. Vždy TLS, nikdy plain AMQP.
• partner-<key-id> — dedikovaný vhost vyhrazený per klíč, takže vaše fronty nikdy nekolidují s frontami jiných partnerů. Key ID je neprůhledný identifikátor vedle API klíče na obrazovce s odhalením.

Po připojení konzumujete ze tří event front (telemetry, alarm, status) a publikujete do tří command front (command, schedule, config). Kompletní seznam front je na detailní stránce API klíče po jeho vytvoření.

Předpoklady

• Účet s rolí ORG_ADMIN v cílové organizaci.
• AMQP 0-9-1 klientská knihovna — amqplib (Node), pika nebo aio-pika (Python), RabbitMQ.Client (.NET).
• Služba se stabilní výstupní (egress) IP. Průvodce vyžaduje CIDR allowlist u každého presetu, který uděluje AMQP.

Krok 1 — Otevřete stránku Connections

Přihlaste se na https://voke.turena.cz, zvolte správnou organizaci a otevřete Workspace settings → Connections (/orgs/<orgId>/settings/connections).

Klikněte na + Connect partner pro otevření průvodce.

Krok 2 — Zvolte preset, který obsahuje vcp:connect

vcp:connect je scope pro AMQP autentizaci. Jakýkoli preset, který ho obsahuje, uděluje přístup k brokeru — vyberte ten, který odpovídá tomu, co integrujete.

Krok 3 — Potvrďte, že je vcp:connect zaškrtnutý

vcp:connect je scope, který broker kontroluje při každém AMQP handshake. Bez něj je spojení odmítnuto dříve, než se vyhodnotí jakýkoli přístup k frontám. Presety Trading platform partner a Telemetry consumer ho předzaškrtnou; u Custom ho zaškrtněte ručně. Jakékoli vcp:write:* scopy, které také zaškrtnete, umožní klíči publikovat na odpovídajících routing keys.

Krok 4 — Pojmenujte klíč, přidejte IP allowlist, vygenerujte

Dejte klíči název, který později poznáte, a partner ID. Klíče nesoucí AMQP vyžadují alespoň jeden CIDR v allowlistu — broker odmítne spojení z jakékoli jiné adresy. Přidejte CIDR a klikněte na Generate.

Server před přesměrováním spustí self-test brokeru proti čerstvě vytvořeným credentials; pokud sonda selže, volání vrátí 500 a žádný bundle se nezobrazí. Úspěšné vytvoření vás přivede na detailní stránku API klíče s odhalovacím bannerem nahoře.

Krok 5 — Zkopírujte bundle

Obrazovka s odhalením zobrazuje čtyři hodnoty. Než obrazovku opustíte, zkopírujte je všechny do svého secret manageru.

• Key ID — neprůhledný identifikátor, který můžete uvádět v support ticketech, aniž byste vyzradili secret.
• API key — plaintext secret. Slouží zároveň jako AMQP heslo i jako REST hlavička X-API-Key.
• HMAC signing key — přítomen pouze tehdy, když klíč nese scope vcp:write:*. Používá se k podpisu vysoce rizikových příkazů (viz Integrita VCP zpráv).
• AMQPS URI — amqps://<org-slug>:<api-key>@amqp.voke.turena.cz:5671/partner-<key-id>. Vložte přímo do jakéhokoli AMQP klienta, který přijímá connection string.

Krok 6 — Připojte se z vašeho klienta

Jakmile kliknete na I've saved these, detailní stránka nahradí secrety jednotlivými připojovacími hodnotami, které můžete přímo vložit do konfigurace vašeho AMQP klienta.

// Node.js — consume telemetry
import * as amqp from 'amqplib';

const URL = process.env.VOKE_AMQPS_URI!; // amqps://<org-slug>:<api-key>@amqp.voke.turena.cz:5671/partner-<key-id>

const conn = await amqp.connect(URL);
const ch = await conn.createChannel();

await ch.consume('vcp.<org-slug>.event.telemetry', (msg) => {
  if (!msg) return;
  const envelope = JSON.parse(msg.content.toString('utf8'));
  console.log(envelope);
  ch.ack(msg);
});

# Python — consume telemetry
import asyncio, os
import aio_pika

async def main():
    conn = await aio_pika.connect_robust(os.environ["VOKE_AMQPS_URI"])
    ch = await conn.channel()
    queue = await ch.get_queue("vcp.<org-slug>.event.telemetry")
    async with queue.iterator() as it:
        async for msg in it:
            async with msg.process():
                print(msg.body.decode("utf-8"))

asyncio.run(main())

Názvy front v přehledu

Broker vám posílá události; vy publikujete příkazy do něj.

Chyby

Další kroky

• Integrita VCP zpráv — kdy a jak HMAC-podepisovat command envelopes.
• AMQP Reference — AsyncAPI specifikace pro každý channel a tvar zprávy.
• REST autentizace — REST protějšek používající stejného průvodce.