logo

Komplexní průvodce webhookem Twitteru

Za poslední 3 měsíce jsem provedl několik vývojových průzkumů s Twitter API. Výsledky byly (nehanebné zástrčky) mé dva projekty, Tweet Scheduler a děkuji vám, další. Moje zkušenost byla přinejmenším méně než hvězdná. Podle mých zkušeností je problém v tom, že dokumentace pro vývojáře Twitter zanechala hodně přání. Největším problémem je Account Activity API, nový koncept webhooku, kterému je docela náročné porozumět a pracovat s ním. Doufám, že v tomto příspěvku vysvětlím, jak to funguje, a vytvořím zábavného Twitter bota, který tyto koncepty zavede do praxe.

Webhook a předplatné

Zde je návod, jak webhook Twitter funguje.

Když používáte Twitter webhook ke sledování uživatele, dostanete upozornění, kdykoli dojde k nové události související s tímto uživatelem. Zde je seznam všech událostí, k jejichž odběru se můžete přihlásit.

Dost jednoduché, že?​

V mnoha produktech je pěkné a hezké uživatelské rozhraní, kde si můžete zaregistrovat adresu URL webhooku. S Twitterem musíte dělat vše programově. Kromě toho Twitter také přidává koncept předplatného.

Dovolte mi, abych pomocí tohoto diagramu podrobněji uvedl předplatné na Twitteru.

V mnoha případech, abyste umožnili uživateli Twitteru přihlásit se k odběru vaší aplikace, musíte zpracovat OAuth a požádat o oprávnění. Zde jsou 2 případy použití, jeden, kdy musíte požádat o povolení, a jeden, kdy ne.

Případ použití 1

Vytváříte robota Twitteru, kde se přihlašuje k odběru svého vlastní činnosti. Například @this_vid, robot Twitteru, který stáhne video pro uživatele při zmínce, se přihlásí k odběru události zmínky.

V tomto případě vám Twitter při vytváření aplikace Twitter z tohoto účtu robota poskytne přístupový token a tajemství, které fungují pouze pro tento účet. Pro tento případ použití je dost dobrý, takže se nemusíte starat o OAuth. K přidání předplatného do vašeho webhooku budete stále muset použít tyto tokeny a tajný kód.

Případ použití 2

Vytváříte robota Twitteru, kde se přihlašuje k odběru ostatních činnosti. Například jako další poděkování se aplikace přihlásí k odběru událostí přímých zpráv mnoha různých uživatelů namísto vlastního účtu Twitter.

V tomto případě musíte požádat o povolení k získání přístupu k jejich aktivitám. To zahrnuje ověřování Twitter pomocí OAuth 1. Poté, co se uživatel přihlásí do vaší aplikace, obdržíte přístupový token a tajný token. Pomocí těchto tokenů pak můžete přidat předplatné tohoto uživatele do svého webhooku.

Abych to shrnul

  • Zaregistrujte webhook na Twitteru pomocí volání API
  • Pro každý účet, jehož aktivity se chcete přihlásit, nejprve požádejte o povolení s protokolem OAuth k načtení přístupového tokenu a tajného tokenu
  • Potom přidejte nové předplatné s dalším voláním API

Cvičení

Takže vám ukážu, jak funguje webhook Twitter vytvořením @GimmeDadJoke. Kdykoli ve svém tweetu zmíníte robota, odpoví vtipem táty.

Vtipy budou získány z icanhazdadjoke.

Vše napíšu v JavaScriptu/NodeJS a nasadím na Zeit Now.

Pojďme na to.

Vytvořit aplikaci Twitter

Nejprve vytvořte nový účet Twitter s požadovaným popisovačem; v mém případě:GimmeDadJoke .

Poté vyplňte Twitter formulář a požádejte o přístup k Twitter API. Může to vypadat děsivě, ale vypadá to jako automatizovaný proces, takže se nebojte.

Po uplatnění a udělení přístupu můžete z tohoto formuláře vytvořit novou aplikaci Twitter.

A nakonec přejděte na Keys and tokens získáte přístup ke klíčům API vaší aplikace.

Odtud klikněte na tlačítko, které vytvoří přístupový token a tajný přístupový token.

Dovolte mi vysvětlit, co tyto tokeny dělají:

  • Consumer API Keys , včetně API key a API secret key , jsou tokeny, které dávají Twitteru vědět, která aplikace volá API. Jsou potřeba při každém volání API, které vaše aplikace provede.
  • Access token a Access token secret jsou tokeny, které identifikují, který uživatel provádí akci. Za každého uživatele, který udělí vaší aplikaci oprávnění, obdržíte jeho přístupový token a tajný přístupový token. V tomto případě tyto dva tokeny patří uživateli vlastníka aplikace. V mém případě účet @GimmeDadJoke .

Dále přejděte na Permissions a změňte své přístupové oprávnění na Read, write, and Direct Messages . I když nepotřebujete přistupovat k DM, stále musíte toto oprávnění používat, protože rozhraní Account Activity API automaticky odesílá data DM do vašeho webhooku.

Nakonec je potřeba vytvořit vývojové prostředí Twitteru pro použití předplatitelských API. Přejděte na řídicí panel prostředí a v části Account Activity API / Sandbox klikněte na tlačítko „Nastavit prostředí pro vývojáře“. Poté budete vyzváni, abyste své prostředí pojmenovali a vybrali, ke které aplikaci patří. V mém případě to pojmenuji development a vyberte aplikaci, kterou jsem právě vytvořil.

A je to. Konečně jsme skončili s nastavením Twitteru a jsme připraveni napsat nějaký kód.

Nastavit

Přejděte do složky podle svého výběru a začněte nastavovat náš kód:

mkdir gimmedadjoke && cd gimmedadjoke

Adresa URL webhooku

Pokud jste Zeit Now dosud nepoužívali, musíte si také nainstalovat jejich CLI a přihlásit se nebo vytvořit účet:

npm i -g now
now login

Nyní jste připraveni nastavit funkci API bez serveru:

mkdir api && cd api
yarn init -y

Uvnitř package.json soubor, přidejte počáteční a sestavení skriptů:

// gimmedadjoke/api/package.json

{
  "scripts": {
    "start": "now dev",
    "build": "now --prod"
  }
}

Nyní vytvoříme funkci webhooku:

// gimmedadjoke/api/webhook.js

const crypto = require("crypto");

function createCrcResponseToken(crcToken) {
  const hmac = crypto
    .createHmac("sha256", process.env.TWITTER_CONSUMER_SECRET)
    .update(crcToken)
    .digest("base64");

  return `sha256=${hmac}`;
}

function getHandler(req, res) {
  const crcToken = req.query.crc_token;

  if (crcToken) {
    res.status(200).send({
      response_token: createCrcResponseToken(crcToken)
    });
  } else {
    res.status(400).send({
      message: "Error: crc_token missing from request."
    });
  }
}

function postHandler(req, res) {
  const body = req.body;
  console.log(body);
  res.status(200).json(body);
}

module.exports = (req, res) => {
  try {
    switch (req.method) {
      case "GET":
        return getHandler(req, res);
      case "POST":
        return postHandler(req, res);
      default:
        return res.status(410).json({ message: "Unsupported Request Method" });
    }
  } catch (error) {
    console.log(error.message);
    res.status(500).send();
  }
};

Nějaké stručné vysvětlení účelu kódu:

  • Tato cesta očekává 2 typy požadavků, GET a POST.
  • Trasa GET slouží k ověření. Když webhook zaregistrujete, Twitter odešle testovací požadavek, aby se ujistil, že jste to vy, kdo ovládá adresu URL webhooku.
  • Trasa POST je pro skutečné události. Kdykoli dojde k nové události, Twitter odešle požadavek POST na tuto trasu. Momentálně zatím nic neděláme.

Chcete-li spustit funkci ve vývojovém režimu, můžete spustit yarn start . Můžete zkusit odeslat požadavek POST na http//localhost:3000/webhook.js pro potvrzení, že vaše funkce funguje.

Nasadit do teď

Chcete-li nastavit nasazení, vytvořte now.json soubor:

// gimmedadjoke/api/now.json

{
  "name": "gimmedadjoke",
  "version": 2,
  "builds": [{ "src": "webhook.js", "use": "@now/node" }],
  "env": {
    "TWITTER_CONSUMER_KEY": "@gimmedadjoke-consumer-key",
    "TWITTER_CONSUMER_SECRET": "@gimmedadjoke-consumer-secret",
    "TWITTER_ACCESS_TOKEN": "@gimmedadjoke-access-token",
    "TWITTER_ACCESS_TOKEN_SECRET": "@gimmedadjoke-access-token-secret"
  }
}

Dále musíte nastavit proměnné prostředí:

now secrets add gimmedadjoke-consumer-key TWITTER_CONSUMER_KEY
now secrets add gimmedadjoke-consumer-secret TWITTER_CONSUMER_SECRET
now secrets add gimmedadjoke-access-token TWITTER_ACCESS_TOKEN
now secrets add gimmedadjoke-access-token-secret TWITTER_ACCESS_TOKEN_SECRET

Nezapomeňte změnit gimmedadjoke na jméno vašeho robota a použijte správné tokeny pro jejich hodnoty.

Poté jste připraveni nasadit svou funkci, která pohání robota Twitteru. Spusťte yarn deploy .

Nyní otestujte, zda je vaše nasazení úspěšné:

Skripty

Jakmile bude vaše nasazení Now připraveno ke spuštění, můžete začít psát několik skriptů Node pro nastavení webhooku a předplatného. 

pwd # make sure you're at your bot root directory
mkdir scripts && cd scripts
yarn init -y
yarn add dotenv request request-promise

Ve vašem .env soubor uvnitř scripts adresář:

TWITTER_API_URL=https://api.twitter.com/1.1
TWITTER_CONSUMER_KEY=your token from app dashboard
TWITTER_CONSUMER_SECRET=your token from app dashboard
TWITTER_ACCESS_TOKEN=your token from app dashboard
TWITTER_ACCESS_TOKEN_SECRET=your token from app dashboard
TWITTER_BEARER_TOKEN=
TWITTER_WEBHOOK_ENV=development (or whatever you name it when creating your dev environment)
WEBHOOK_URL=https://gimmedadjoke.now.sh/webhook.js (your Now webhook function)

Počkejte, co je to za tajemný token nositele?

Bearer Token je dalším způsobem, jak se vaše aplikace ověřuje na Twitteru. Docela matoucí, já vím. Nebojte se, provedu vás kódem, který se chystáme napsat.

Aby byly soubory skriptů jednodušší, napíšete velké api soubor, který se stará o interakci Twitter API. Zde je vše, co budeme dělat s našimi skripty:

// gimmedadjoke/scripts/src/api.js

require("dotenv").config();
const request = require("request-promise");

const TWITTER_API_URL = process.env.TWITTER_API_URL;
const TWITTER_CONSUMER_KEY = process.env.TWITTER_CONSUMER_KEY;
const TWITTER_CONSUMER_SECRET = process.env.TWITTER_CONSUMER_SECRET;
const TWITTER_ACCESS_TOKEN = process.env.TWITTER_ACCESS_TOKEN;
const TWITTER_ACCESS_TOKEN_SECRET = process.env.TWITTER_ACCESS_TOKEN_SECRET;
const TWITTER_BEARER_TOKEN = process.env.TWITTER_BEARER_TOKEN;
const TWITTER_WEBHOOK_ENV = process.env.TWITTER_WEBHOOK_ENV;

const oauth = {
  consumer_key: TWITTER_CONSUMER_KEY,
  consumer_secret: TWITTER_CONSUMER_SECRET,
  token: TWITTER_ACCESS_TOKEN,
  token_secret: TWITTER_ACCESS_TOKEN_SECRET
};

const authorizationHeaders = {
  authorization: `Bearer ${TWITTER_BEARER_TOKEN}`
};

exports.getBearerToken = function() {
 return [request.post](http://request.post)({
    url: "[https://api.twitter.com/oauth2/token?grant_type=client_credentials](https://api.twitter.com/oauth2/token?grant_type=client_credentials)",
    auth: {
      user: process.env.TWITTER_CONSUMER_KEY,
      pass: process.env.TWITTER_CONSUMER_SECRET
    },
    json: true
  });
};

exports.getWebhook = function() {
  return request.get({
    url: `${TWITTER_API_URL}/account_activity/all/${TWITTER_WEBHOOK_ENV}/webhooks.json`,
    headers: authorizationHeaders,
    json: true
  });
};

exports.createWebhook = function(webhookUrl) {
  return [request.post](http://request.post)({
    url: `${TWITTER_API_URL}/account_activity/all/${TWITTER_WEBHOOK_ENV}/webhooks.json`,
    oauth,
    form: {
      url: webhookUrl
    },
    json: true
  });
};

exports.deleteWebhook = function(webhookId) {
  return request.delete({
    url: `${TWITTER_API_URL}/account_activity/all/${TWITTER_WEBHOOK_ENV}/webhooks/${webhookId}.json`,
    oauth
  });
};

exports.getSubscription = function() {
  return request.get({
    url: `${TWITTER_API_URL}/account_activity/all/${this.webhookEnv}/subscriptions.json`,
    oauth,
    json: true
  });
};

exports.createSubscription = function() {
  return request.post({
    url: `${TWITTER_API_URL}/account_activity/all/${TWITTER_WEBHOOK_ENV}/subscriptions.json`,
    oauth,
    json: true
  });
};

exports.deleteSubscription = function(userId) {
  return request.delete({
    url: `${TWITTER_API_URL}/account_activity/all/${this.webhookEnv}/subscriptions/${userId}.json`,
    headers: authorizationHeaders,
    json: true
  });
};

Zde jsou všechny funkce, které jsme napsali:

  • getBearerToken
  • getWebhook
  • vytvořit webhook
  • deleteWebhook
  • getSubscription
  • vytvořit předplatné
  • deleteSubscription

Vytvoříme 7 skriptů, které přímo korelují s těmito funkcemi později .

Mezitím:

Dejte si pauzu

Hej, děkuji za sledování. Vím, že to bylo hodně kódu, ale to je většina kódu pro tuto sekci.

Až se vrátíte, vysvětlím vám, co tyto funkce skutečně dělají, a doufejme, že získáte lepší a praktičtější pochopení toho, jak webhook Twitter skutečně funguje.

Teď si jdi dát svačinu nebo si dej šálek čaje. Úplně si to zasloužíš.

Token nositele

Nejprve napíšeme skript pro načtení vašeho tokenu nosiče aplikace:

// gimmedadjoke/scripts/src/bearerToken.js

const api = require("./api");

function run() {
  api
    .getBearerToken()
    .then(response => {
      console.log(response);
    })
    .catch(error => {
      console.log(error.message);
    });
}

run();

Poté v terminálu:

pwd # make sure you're inside the scripts directory
node src/bearerToken.js

Pokud jde vše dobře, měli byste vidět něco takového:

{
  token_type: 'bearer',
  access_token: 'some_token'
}

Zkopírujte tento token a vložte jej do .env soubor. Jste připraveni napsat nějakou dobrotu pro webhooky.

Webhook

Pojďme se zahřát napsáním skriptu, který načte všechny aktuální webhooky spojené s naší aplikací. 

// gimmedadjoke/scripts/src/webhook.get.js

const api = require("./api");

function run() {
  api
    .getWebhook()
    .then(response => {
      console.log(response);
    })
    .catch(error => {
      console.log(error.message);
    });
}

run();

Poté spusťte node src/webhook.get.js . Pokud je odpověď [] , jste na správné cestě.

Přidání webhooku do aplikace:

// gimmedadjoke/scripts/src/webhook.post.js

const api = require("./api");

const WEBHOOK_URL = process.env.WEBHOOK_URL;

function run() {
  api
    .createWebhook(WEBHOOK_URL)
    .then(response => {
      console.log(response);
    })
    .catch(error => {
      console.log(error.message);
    });
}

run();

Když jej spustíte, můžete si všimnout, že to trvá o něco déle než jiné příkazy, které jste spustili. To proto, že se toho tady hodně děje:

  • Požádali jste Twitter, aby zaregistroval vaši adresu URL webhooku.
  • Twitter odeslal vaší funkci požadavek na test v aplikaci Now.
  • Jakmile bude služba úspěšně otestována, Twitter vám odpověděl s informacemi o vašem novém webhooku.

A nakonec vytvořte skript, který odstraní webhook:

// gimmedadjoke/scripts/src/webhook.delete.js

const api = require("./api");

function run() {
  api
    .getWebhook()
    .then(response => {
      const webhookId = response[0].id;
      api
        .deleteWebhook(webhookId)
        .then(response => {
          console.log("Successfully delete webhook");
        })
        .catch(error => {
          console.log(error.message);
        });
    })
    .catch(error => {
      console.log(error.message);
    });
}

run();

Nyní pomocí těchto 3 skriptů můžete zaregistrovat svůj webhook, získat jeho informace a kdykoli jej odstranit.

I když svůj webhook můžete zaregistrovat, zatím nic nedělá. Musíte také použít subscription aby byl váš webhook funkční.

Předplatné

Podobně jako u skriptů, které jste napsali pro webhooky, nyní napíšete další 3 skripty pro předplatné. Ukážu vám kód a můžeme si o něm promluvit později:

// gimmedadjoke/scripts/src/subscription.get.js

const api = require("./api");

function run() {
  api
    .createSubscription()
    .then(response => {
      console.log("Successfully subscribe the app owner user to webhook.");
    })
    .catch(error => {
      console.log(error.message);
    });
}

run();

// gimmedadjoke/scripts/src/subscription.post.js

const api = require("./api");

function run() {
  api
    .createSubscription()
    .then(response => {
      console.log("Successfully subscribe the app owner user to webhook.");
    })
    .catch(error => {
      console.log(error.message);
    });
}

run();

// gimmedadjoke/scripts/src/subscription.delete.js

const api = require("./api");

function run() {
  const userId = process.env.TWITTER_ACCESS_TOKEN.split("-")[0];

  api
    .deleteSubscription(userId)
    .then(response => {
      console.log("Successfully remove subscription.");
    })
    .catch(error => {
      console.log(error.message);
    });
}

run();

Zkuste se přihlásit k odběru svého webhooku vlastníka aplikace na Twitteru (uživatel spojený s účtem vývojáře – tedy v tomto případě @gimmedadjoke). 

node src/subscription.post.js

Pokud váš skript běží bez chyby, gratulujeme, váš webhook je nyní v akci.

V mém případě vždy, když uživatel Twitteru @GimmeDadJoke přijme jakoukoli novou událost, budu o ní vědět.

Můžete to potvrdit zasláním přímé zprávy vašemu Twitter botovi a zkontrolovat protokol funkce.

🎉🎉

Odpovězte vtipem táty

Protože toto není předmětem této příručky, můžete si skutečné zpracování požadavku webhooku prohlédnout ve zdrojovém kódu.

Obecně to můžete zvládnout takto:

function postHandler(req, res) {
  const body = req.body;

  if (body[THE_EVENT_YOU_CARE_ABOUT]) {
    // do stuff

    return res.status(200).send();
  } else {
    return res.status(200).send();
  }
}

Konečný výsledek:

🎉🎉

Rozšiřte robota Twitteru o odběr událostí jiných uživatelů

Od této chvíle robot poslouchá vlastní událost na Twitteru. Můžete jej rozšířit a přihlásit se k odběru i dalším uživatelům. Tento případ použití přesahuje rámec této příručky, ale poskytnu vám obecný přístup k jeho implementaci.

Možná to pro vás může být zábavná výzva.

Zde je obecný přístup:

  • Implementujte funkci „přihlášení pomocí Twitteru“ pomocí protokolu OAuth. Jedním ze způsobů, jak toho dosáhnout, je použít Firebase.
  • Jakmile se přihlásíte, vaše aplikace obdrží přístupový token a tajný klíč přístupového tokenu.
  • Pomocí těchto tokenů přidáte svému robotovi nové předplatné. Je to úplně stejné, jako když přidáte předplatné svému vlastnímu uživateli robota:
request.post({
  url: `${TWITTER_API_URL}/account_activity/all/${TWITTER_WEBHOOK_ENV}/subscriptions.json`,
  oauth: {
    consumer_key: process.env.TWITTER_CONSUMER_KEY,
    consumer_secret: process.env.TWITTER_CONSUMER_SECRET,
    token: ----->YOUR_USER_ACCESS_TOKEN_THAT_YOU_JUST_ACQUIRED,
    token_secret: ----->YOUR_USER_ACCESS_TOKEN_SECRET_THAT_YOU_JUST_ACQUIRED,
  },
  json: true
});

Jakmile je váš uživatel přihlášen k odběru, vaše funkce webhooku obdrží požadavek POST pokaždé, když nastane nová událost.

Omezení

Při používání bezplatné úrovně Twitter API existuje mnoho omezení. Zde je několik, které se přímo týkají webhooků:

  • Pro předplatné můžete mít pouze 1 vývojové prostředí.
  • V tomto prostředí můžete mít pouze 15 předplatných. To znamená, že pokud se vaše aplikace chce přihlásit k odběru mnoha uživatelů (případ použití 2), můžete mít pouze 15 uživatelů na bezplatné úrovni.

CLI

Aktivně pracuji na nástroji příkazového řádku s otevřeným zdrojovým kódem, který by usnadnil tento proces registrace webhooku a správy předplatného. Zůstaňte naladěni na aktualizace a budu rád za vaši spolupráci, pokud se chcete zapojit.

Zdroje

  • Dokumentace rozhraní Twitter API
  • Ukázkový webhook Twitteru na GitHubu:Vývojářský tým Twitteru pro vás vytvořil ukázkový řídicí panel, abyste mohli tento proces zvládnout. To je velmi užitečné a vřele doporučuji, abyste si to prověřili. Díky tomuto projektu jsem začal s webhookem Twitter.

Děkuji, že jste si prohlédli mého průvodce na Twitteru webhook.

Neváhejte mi napsat ping, pokud narazíte na nějaký problém, a dejte mi prosím vědět, až z toho něco postavíte. Těším se, až uvidím všechny ty skvělé věci, které stavíte na Twitteru.