← Cloudflare Workers / workers / tutorials

SMS oznámení GitHub pomocí Twilia

V tomto tutoriálu se naučíte sestavit systém SMS notifikací na Workers, který vás bude informovat o dění v repozitáři GitHub. Váš Worker vám pomocí Twilio odešle textovou zprávu, kdykoli v repozitáři dojde k nové aktivitě.

Naučíte se, jak:

• Vytvářejte webhooky pomocí Workers.
• Propojte Workers s GitHub a Twilio.
• Použijte tajné hodnoty Workeru s Wrangler.

Všechny návody předpokládají, že jste již dokončili Úvodní návod, který vás provede nastavením účtu Cloudflare Workers, C3 ↗, a Wrangler.

Začněte pomocí npm create cloudflare@latest pro vytvoření projektu Worker v příkazovém řádku:

npm create cloudflare@latest -- github-twilio-notifications

Při nastavení vyberte následující možnosti:

• Pro S čím byste chtěli začít?, vyberte Hello World example.
• Pro Jakou šablonu chcete použít?, vyberte Worker only.
• Pro Jaký jazyk chcete použít?, vyberte JavaScript.
• Pro Chcete používat git pro správu verzí?, vyberte Yes.
• Pro Chcete nasadit svou aplikaci?, vyberte No (před nasazením provedeme ještě několik změn).

Poznamenejte si URL, na kterou byla vaše aplikace nasazena. Budete ji potřebovat při konfiguraci GitHub webhooku.

cd github-twilio-notifications

Uvnitř svého nového github-sms-notifications adresář, src/index.js představuje vstupní bod vaší aplikace Cloudflare Workers. Tento soubor budete konfigurovat po většinu tohoto tutoriálu.

Pro tento tutoriál budete také potřebovat účet GitHub a repozitář. Pokud je ještě nemáte, vytvořte nový účet GitHub ↗ a vytvořte nový repozitář ↗ pro pokračování v tomto tutoriálu.

Nejprve vytvořte pro svůj repozitář webhook, který bude odesílat aktualizace vašemu Workeru. Uvnitř Workeru pak tyto aktualizace zpracujete. Nakonec odešlete POST požadavek na Twilio, aby vám odeslal textovou zprávu.

Hotový kód najdete v tomto Repozitář GitHub ↗.

Nejprve nakonfigurujte webhook GitHub tak, aby při aktualizaci repozitáře odesílal data na váš Worker:

1. Přejděte do repozitáře na GitHubu do sekce Nastavení > Webhooks > Přidat webhook.

2. Nastavte Payload URL na /webhook cestu na URL Workeru, kterou jste si poznamenali při prvním nasazení aplikace.

3. V Typ obsahu rozbalovací nabídce vyberte application/json.

4. V Secret pole zadejte tajný klíč podle vlastního výběru.

5. V Které události mají tento webhook spouštět?, vyberte Chci si vybrat jednotlivé události. Vyberte události, pro které chcete dostávat oznámení (například Pull requesty, Odeslání, a Vytvoření větve nebo tagu).

6. Vyberte Přidat webhook k dokončení konfigurace.

Jakmile máte nastavené lokální prostředí, zpracujte aktualizaci repozitáře pomocí svého Workeru.

Zpočátku váš vygenerovaný index.js by mělo vypadat takto:

export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};

Použijte request.method vlastnost objektu Request pro kontrolu, zda je požadavek přicházející do vaší aplikace POST požadavek a odešlete chybovou odpověď, pokud požadavek není POST požadavek.

export default {
	async fetch(request, env, ctx) {
		if (request.method !== "POST") {
			return new Response("Please send a POST request!");
		}
	},
};

Dále ověřte, že je požadavek odeslán se správným tajným klíčem. GitHub připojuje hash podpis pro každý payload pomocí tajného klíče ↗. Použijte pomocnou funkci nazvanou checkSignature na požadavku, aby se ověřilo, že je hash správný. Poté můžete data z webhooku získat zpracováním požadavku jako JSON.

async fetch(request, env, ctx) {
  if(request.method !== 'POST') {
    return new Response('Please send a POST request!');
  }
  try {
    const rawBody = await request.text();

    if (!checkSignature(rawBody, request.headers, env.GITHUB_SECRET_TOKEN)) {
      return new Response("Wrong password, try again", {status: 403});
    }
  } catch (e) {
    return new Response(`Error:  ${e}`);
  }
},

checkSignature funkce použije knihovnu Node.js crypto k zahashování přijatého payloadu pomocí vašeho known tajného klíče, aby se ověřilo, že odpovídá hashi požadavku. GitHub počítá hash ve formátu SHA-256 pomocí HMAC hexdigest. Tuto funkci umístíte na začátek vašeho index.js soubor před svým exportem.

import { createHmac, timingSafeEqual } from "node:crypto";
import { Buffer } from "node:buffer";

function checkSignature(text, headers, githubSecretToken) {
	const hmac = createHmac("sha256", githubSecretToken);
	hmac.update(text);
	const expectedSignature = hmac.digest("hex");
	const actualSignature = headers.get("x-hub-signature-256");

	const trusted = Buffer.from(`sha256=${expectedSignature}`, "ascii");
	const untrusted = Buffer.from(actualSignature, "ascii");

	return (
		trusted.byteLength == untrusted.byteLength &&
		timingSafeEqual(trusted, untrusted)
	);
}

Aby to fungovalo, musíte použít wrangler secret put pro nastavení GITHUB_SECRET_TOKEN. Tento token je secret, který jste zvolili dříve při konfiguraci GitHub webhooku:

npx wrangler secret put GITHUB_SECRET_TOKEN

Přidejte příznak nodejs_compat do souboru Wrangler:

{
	"compatibility_flags": [
		"nodejs_compat"
	]
}

compatibility_flags = [ "nodejs_compat" ]

Pomocí Twilio si budete posílat textovou zprávu o aktivitě ve svém repozitáři. Potřebujete účet Twilio a telefonní číslo, které umí přijímat textové zprávy. Postup nastavení najdete v průvodci Twilio ↗. (Pokud s Twiliem začínáte, mají interaktivní hra ↗ kde se můžete dozvědět, jak jejich platformu používat, a získat nějaké kredity zdarma pro nové uživatele služby.)

Poté můžete vytvořit pomocnou funkci pro odesílání textových zpráv odesláním POST požadavek na endpoint Twilio API. Podívejte se do referenční dokumentace Twilio ↗ kde se dozvíte více o tomto endpointu.

Vytvořte novou funkci s názvem sendText() která bude mít na starosti odeslání požadavku na Twilio:

async function sendText(accountSid, authToken, message) {
	const endpoint = `https://api.twilio.com/2010-04-01/Accounts/${accountSid}/Messages.json`;

	const encoded = new URLSearchParams({
		To: "%YOUR_PHONE_NUMBER%",
		From: "%YOUR_TWILIO_NUMBER%",
		Body: message,
	});

	const token = btoa(`${accountSid}:${authToken}`);

	const request = {
		body: encoded,
		method: "POST",
		headers: {
			Authorization: `Basic ${token}`,
			"Content-Type": "application/x-www-form-urlencoded",
		},
	};

	const response = await fetch(endpoint, request);
	const result = await response.json();

	return Response.json(result);
}

Aby to fungovalo, musíte nastavit několik secrets, abyste skryli svůj ACCOUNT_SID a AUTH_TOKEN ze zdrojového kódu. Tajné hodnoty můžete nastavit pomocí wrangler secret put v příkazovém řádku.

npx wrangler secret put TWILIO_ACCOUNT_SID
npx wrangler secret put TWILIO_AUTH_TOKEN

Upravte svůj githubWebhookHandler pro odeslání textové zprávy pomocí sendText funkci, kterou jste právě vytvořili.

async fetch(request, env, ctx) {
  if(request.method !== 'POST') {
    return new Response('Please send a POST request!');
  }
  try {
    const rawBody = await request.text();
    if (!checkSignature(rawBody, request.headers, env.GITHUB_SECRET_TOKEN)) {
      return new Response('Wrong password, try again', {status: 403});
    }

    const action = request.headers.get('X-GitHub-Event');
    const json = JSON.parse(rawBody);
    const repoName = json.repository.full_name;
    const senderName = json.sender.login;

    return await sendText(
      env.TWILIO_ACCOUNT_SID,
      env.TWILIO_AUTH_TOKEN,
      `${senderName} completed ${action} onto your repo ${repoName}`
    );
  } catch (e) {
    return new Response(`Error:  ${e}`);
  }
};

Spustit npx wrangler deploy příkaz pro opětovné nasazení projektu Worker:

npx wrangler deploy

Nyní, když provedete aktualizaci (kterou jste nakonfigurovali v GitHub Webhook nastavení) do vašeho repozitáře, brzy poté obdržíte zprávu. Pokud jste nikdy předtím nepoužívali Git, přečtěte si Návod na Git push a pull ↗ pro nahrávání (push) do vašeho repozitáře.

Podívejte se na hotový kód na GitHubu ↗.

Dokončením tohoto tutoriálu jste se naučili, jak vytvářet webhooky pomocí Workers, integrovat Workers s GitHub a Twilio a používat tajné klíče Workeru s Wrangler.

• Vytvořte aplikaci JAMStack
• Vytvořte generátor QR kódů