Slack チュートリアル - スラッシュ コマンド(第 1 世代)


このチュートリアルでは Cloud Run functions を使用して、Google Knowledge Graph API を検索する Slack スラッシュ コマンドの実装方法について説明します。

目標

  • Slack でスラッシュ コマンドを作成する。
  • Cloud Run HTTP 関数を作成してデプロイする。
  • Slash コマンドを使って Google Knowledge Graph API を検索する。

費用

このドキュメントでは、課金対象である次の Google Cloudコンポーネントを使用します。

  • Cloud Run functions

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。

新規の Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

始める前に

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Cloud Functions, Cloud Build, and Google Knowledge Graph Search APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. 外部 ID プロバイダ(IdP)を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

  7. gcloud CLI を初期化するには、次のコマンドを実行します。

    gcloud init
  8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the Cloud Functions, Cloud Build, and Google Knowledge Graph Search APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  11. Install the Google Cloud CLI.

  12. 外部 ID プロバイダ(IdP)を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

  13. gcloud CLI を初期化するには、次のコマンドを実行します。

    gcloud init
  14. gcloud CLI がすでにインストールされている場合は、次のコマンドを実行して更新します。

    gcloud components update
  15. 開発環境を準備します。
  16. データの流れ

    Slack のスラッシュ コマンドのチュートリアル アプリケーションでのデータの流れは次のとおりです。

    1. ユーザーが Slack チャネルで /kg <search_query> スラッシュ コマンドを実行します。
    2. Slack がコマンドのペイロードを関数のトリガー エンドポイントに送信します。
    3. 関数がユーザーの検索クエリとともにリクエストを Knowledge Graph API に送信します。
    4. Knowledge Graph API は、レスポンスで一致した結果を返します。
    5. 関数はフォーマット化したレスポンス内容を Slack メッセージに保存します。
    6. 関数はメッセージを Slack に送信します。
    7. ユーザーは Slack チャンネルでフォーマット化されたレスポンスを確認します。

    次はこの手順を可視化した図です。

    Knowledge Graph API キーの作成

    Google Cloud コンソールの [認証情報] ページで、[認証情報の作成] ボタンをクリックして [API キー] を選択します。このキーは、次のセクションで Knowledge Graph API にアクセスするときに使用します。

    関数の準備

    1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

      Node.js

      git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

      または、zip 形式のサンプルをダウンロードしてファイルを抽出してもかまいません。

      Python

      git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

      または、zip 形式のサンプルをダウンロードしてファイルを抽出してもかまいません。

      Go

      git clone https://github.com/GoogleCloudPlatform/golang-samples.git

      または、zip 形式のサンプルをダウンロードしてファイルを抽出してもかまいません。

      Java

      git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

      または、zip 形式のサンプルをダウンロードし、ファイルを抽出してもかまいません。

      Ruby

      git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git

      または、zip 形式のサンプルをダウンロードしてファイルを抽出してもかまいません。

    2. Cloud Run functions のサンプルコードが含まれているディレクトリに移動します。

      Node.js

      cd nodejs-docs-samples/functions/slack/

      Python

      cd python-docs-samples/functions/slack/

      Go

      cd golang-samples/functions/slack/

      Java

      cd java-docs-samples/functions/slack/

      Ruby

      cd ruby-docs-samples/functions/slack/

    関数のデプロイ

    ユーザー(または Slack)が関数のエンドポイントに HTTP POST リクエストを送信したときに実行される関数をデプロイするには、サンプルコード(または Java の pom.xml ファイル)を含むディレクトリで次のコマンドを実行します。

    YOUR_SLACK_SIGNING_SECRET は、アプリの構成の [Basic information] ページで、Slack から提供された署名シークレットに置き換えます。YOUR_KG_API_KEY は、前に作成した Knowledge Graph API Key で置き換えます。

    Node.js

    gcloud functions deploy kgSearch \
    --runtime nodejs20 \
    --trigger-http \
    --set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET,KG_API_KEY=YOUR_KG_API_KEY" \
    --allow-unauthenticated

    サポートされている Node.js バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

    Python

    gcloud functions deploy kg_search \
    --runtime python312 \
    --trigger-http \
    --set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET,KG_API_KEY=YOUR_KG_API_KEY" \
    --allow-unauthenticated

    サポートされている Python バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

    Go

    gcloud functions deploy KGSearch \
    --runtime go121 \
    --trigger-http \
    --set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET,KG_API_KEY=YOUR_KG_API_KEY" \
    --allow-unauthenticated

    サポートされている Go バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

    Java

    gcloud functions deploy java-slack-function \
    --entry-point functions.SlackSlashCommand \
    --runtime java17 \
    --memory 512MB \
    --trigger-http \
    --set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET,KG_API_KEY=YOUR_KG_API_KEY" \
    --allow-unauthenticated

    サポートされている Java バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

    Ruby

    gcloud functions deploy kg_search --runtime ruby33 \
    -
    -trigger-http \
    -
    -set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET,KG_API_KEY=YOUR_KG_API_KEY" \
    -
    -allow-unauthenticated

    サポートされている Ruby バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

    アプリケーションの構成

    関数をデプロイした後、Slack スラッシュ コマンドを作成する必要があります。このコマンドがトリガーされるたびに関数にクエリが送信されます。

    1. Slack のスラッシュ コマンドをホストする Slack アプリを作成します。統合のインストール権限が与えられている Slack チームにそれを関連付けます。

    2. [Slash commands] に移動し、[Create new command] ボタンをクリックします。

    3. コマンドの名前として「/kg」を入力します。

    4. コマンドの URL を入力します。

      Node.js

      https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kgSearch

      Python

      https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kg_search

      Go

      https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/KGSearch

      Java

      https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/java-slack-function

      Ruby

      https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kg_search

      ここで、YOUR_REGION は、関数がデプロイされているリージョンであり、YOUR_PROJECT_ID は Cloud プロジェクト ID です。

      関数のデプロイが完了すると、両方の値がターミナルに表示されます。

    5. [保存] をクリックします。

    6. [Basic Information] に移動します。

    7. [Install your app to your workspace] をクリックし、画面の指示に従って、ワークスペース用にアプリケーションを有効にします。

      少し待つと、Slack Slash コマンドがオンラインになります。

    コードについて

    依存関係をインポートする

    アプリケーションが Google Cloud Platform サービスとやり取りするには、いくつかの依存関係をインポートする必要があります。

    Node.js

    const functions = require('@google-cloud/functions-framework');
    const google = require('@googleapis/kgsearch');
    const {verifyRequestSignature} = require('@slack/events-api');
    
    // Get a reference to the Knowledge Graph Search component
    const kgsearch = google.kgsearch('v1');

    Python

    import os
    
    from flask import jsonify
    import functions_framework
    import googleapiclient.discovery
    from slack.signature import SignatureVerifier
    
    
    kgsearch = googleapiclient.discovery.build(
        "kgsearch", "v1", developerKey=os.environ["KG_API_KEY"], cache_discovery=False
    )

    Go

    
    package slack
    
    import (
    	"context"
    	"log"
    	"os"
    
    	"google.golang.org/api/kgsearch/v1"
    	"google.golang.org/api/option"
    )
    
    var (
    	entitiesService *kgsearch.EntitiesService
    	kgKey           string
    	slackSecret     string
    )
    
    func setup(ctx context.Context) {
    	kgKey = os.Getenv("KG_API_KEY")
    	slackSecret = os.Getenv("SLACK_SECRET")
    
    	if entitiesService == nil {
    		kgService, err := kgsearch.NewService(ctx, option.WithAPIKey(kgKey))
    		if err != nil {
    			log.Fatalf("kgsearch.NewService: %v", err)
    		}
    		entitiesService = kgsearch.NewEntitiesService(kgService)
    	}
    }
    

    Java

    private static final Logger logger = Logger.getLogger(SlackSlashCommand.class.getName());
    private static final String API_KEY = getenv("KG_API_KEY");
    private static final String SLACK_SECRET = getenv("SLACK_SECRET");
    private static final Gson gson = new Gson();
    
    private final String apiKey;
    private final Kgsearch kgClient;
    private final SlackSignature.Verifier verifier;
    
    public SlackSlashCommand() throws IOException, GeneralSecurityException {
      this(new SlackSignature.Verifier(new SlackSignature.Generator(SLACK_SECRET)));
    }
    
    SlackSlashCommand(SlackSignature.Verifier verifier) throws IOException, GeneralSecurityException {
      this(verifier, API_KEY);
    }
    
    SlackSlashCommand(SlackSignature.Verifier verifier, String apiKey)
        throws IOException, GeneralSecurityException {
      this.verifier = verifier;
      this.apiKey = apiKey;
      this.kgClient = new Kgsearch.Builder(
          GoogleNetHttpTransport.newTrustedTransport(), new GsonFactory(), null).build();
    }
    
    // Avoid ungraceful deployment failures due to unset environment variables.
    // If you get this warning you should redeploy with the variable set.
    private static String getenv(String name) {
      String value = System.getenv(name);
      if (value == null) {
        logger.warning("Environment variable " + name + " was not set");
        value = "MISSING";
      }
      return value;
    }

    Ruby

    require "functions_framework"
    require "slack-ruby-client"
    require "google/apis/kgsearch_v1"
    
    # This block is executed during cold start, before the function begins
    # handling requests. This is the recommended way to create shared resources
    # and objects.
    FunctionsFramework.on_startup do
      # Create a global handler object, configured with the environment-provided
      # API key and signing secret.
      kg_search = KGSearch.new kg_api_key:     ENV["KG_API_KEY"],
                               signing_secret: ENV["SLACK_SECRET"]
      set_global :kg_search, kg_search
    end
    
    # The KGSearch class implements the logic of validating and responding
    # to requests. More methods of this class are shown below.
    class KGSearch
      def initialize kg_api_key:, signing_secret:
        # Create the global client for the Knowledge Graph Search Service,
        # configuring it with your API key.
        @client = Google::Apis::KgsearchV1::KgsearchService.new
        @client.key = kg_api_key
    
        # Save signing secret for use by the signature validation method.
        @signing_secret = signing_secret
      end

    Webhook の受信

    ユーザー(または Slack)が関数のエンドポイントに HTTP POST リクエストを送信すると、次の関数が実行されます。

    Node.js

    /**
     * Receive a Slash Command request from Slack.
     *
     * Trigger this function by creating a Slack slash command with the HTTP Trigger URL.
     * You can find the HTTP URL in the Cloud Console or using `gcloud functions describe`
     *
     * @param {object} req Cloud Function request object.
     * @param {object} req.body The request payload.
     * @param {string} req.rawBody Raw request payload used to validate Slack's message signature.
     * @param {string} req.body.text The user's search query.
     * @param {object} res Cloud Function response object.
     */
    functions.http('kgSearch', async (req, res) => {
      try {
        if (req.method !== 'POST') {
          const error = new Error('Only POST requests are accepted');
          error.code = 405;
          throw error;
        }
    
        if (!req.body.text) {
          const error = new Error('No text found in body.');
          error.code = 400;
          throw error;
        }
    
        // Verify that this request came from Slack
        verifyWebhook(req);
    
        // Make the request to the Knowledge Graph Search API
        const response = await makeSearchRequest(req.body.text);
    
        // Send the formatted message back to Slack
        res.json(response);
    
        return Promise.resolve();
      } catch (err) {
        console.error(err);
        res.status(err.code || 500).send(err);
        return Promise.reject(err);
      }
    });

    Python

    @functions_framework.http
    def kg_search(request):
        if request.method != "POST":
            return "Only POST requests are accepted", 405
    
        verify_signature(request)
        kg_search_response = make_search_request(request.form["text"])
        return jsonify(kg_search_response)
    
    

    Go

    
    // Package slack is a Cloud Function which recieves a query from
    // a Slack command and responds with the KG API result.
    package slack
    
    import (
    	"bytes"
    	"crypto/hmac"
    	"crypto/sha256"
    	"encoding/hex"
    	"encoding/json"
    	"fmt"
    	"io"
    	"log"
    	"net/http"
    	"strconv"
    	"strings"
    	"time"
    )
    
    type oldTimeStampError struct {
    	s string
    }
    
    func (e *oldTimeStampError) Error() string {
    	return e.s
    }
    
    const (
    	version                     = "v0"
    	slackRequestTimestampHeader = "X-Slack-Request-Timestamp"
    	slackSignatureHeader        = "X-Slack-Signature"
    )
    
    type attachment struct {
    	Color     string `json:"color"`
    	Title     string `json:"title"`
    	TitleLink string `json:"title_link"`
    	Text      string `json:"text"`
    	ImageURL  string `json:"image_url"`
    }
    
    // Message is the a Slack message event.
    // see https://api.slack.com/docs/message-formatting
    type Message struct {
    	ResponseType string       `json:"response_type"`
    	Text         string       `json:"text"`
    	Attachments  []attachment `json:"attachments"`
    }
    
    // KGSearch uses the Knowledge Graph API to search for a query provided
    // by a Slack command.
    func KGSearch(w http.ResponseWriter, r *http.Request) {
    	setup(r.Context())
    
    	bodyBytes, err := io.ReadAll(r.Body)
    	if err != nil {
    		log.Fatalf("Couldn't read request body: %v", err)
    	}
    	r.Body = io.NopCloser(bytes.NewBuffer(bodyBytes))
    
    	if r.Method != "POST" {
    		http.Error(w, "Only POST requests are accepted", http.StatusMethodNotAllowed)
    	}
    	if err := r.ParseForm(); err != nil {
    		http.Error(w, "Couldn't parse form", 400)
    		log.Fatalf("ParseForm: %v", err)
    	}
    
    	// Reset r.Body as ParseForm depletes it by reading the io.ReadCloser.
    	r.Body = io.NopCloser(bytes.NewBuffer(bodyBytes))
    	result, err := verifyWebHook(r, slackSecret)
    	if err != nil {
    		log.Fatalf("verifyWebhook: %v", err)
    	}
    	if !result {
    		log.Fatalf("signatures did not match.")
    	}
    
    	if len(r.Form["text"]) == 0 {
    		log.Fatalf("empty text in form")
    	}
    	kgSearchResponse, err := makeSearchRequest(r.Form["text"][0])
    	if err != nil {
    		log.Fatalf("makeSearchRequest: %v", err)
    	}
    	w.Header().Set("Content-Type", "application/json")
    	if err = json.NewEncoder(w).Encode(kgSearchResponse); err != nil {
    		log.Fatalf("json.Marshal: %v", err)
    	}
    }
    

    Java

    /**
     * Receive a Slash Command request from Slack.
     *
     * @param request Cloud Function request object.
     * @param response Cloud Function response object.
     * @throws IOException if Knowledge Graph request fails
     */
    @Override
    public void service(HttpRequest request, HttpResponse response) throws IOException {
    
      // Validate request
      if (!"POST".equals(request.getMethod())) {
        response.setStatusCode(HttpURLConnection.HTTP_BAD_METHOD);
        return;
      }
    
      // reader can only be read once per request, so we preserve its contents
      String bodyString = request.getReader().lines().collect(Collectors.joining());
    
      // Slack sends requests as URL-encoded strings
      //   Java 11 doesn't have a standard library
      //   function for this, so do it manually
      Map<String, String> body = new HashMap<>();
      for (String keyValuePair : bodyString.split("&")) {
        String[] keyAndValue = keyValuePair.split("=");
        if (keyAndValue.length == 2) {
          String key = keyAndValue[0];
          String value = keyAndValue[1];
    
          body.put(key, value);
        }
      }
    
      if (body == null || !body.containsKey("text")) {
        response.setStatusCode(HttpURLConnection.HTTP_BAD_REQUEST);
        return;
      }
    
      if (!isValidSlackWebhook(request, bodyString)) {
        response.setStatusCode(HttpURLConnection.HTTP_UNAUTHORIZED);
        return;
      }
    
      String query = body.get("text");
    
      // Call knowledge graph API
      JsonObject kgResponse = searchKnowledgeGraph(query);
    
      // Format response to Slack
      // See https://api.slack.com/docs/message-formatting
      BufferedWriter writer = response.getWriter();
    
      writer.write(formatSlackMessage(kgResponse, query));
    
      response.setContentType("application/json");
    }

    Ruby

    # Handler for the function endpoint.
    FunctionsFramework.http "kg_search" do |request|
      # Return early if the request is not a POST.
      unless request.post?
        return [405, {}, ["Only POST requests are accepted."]]
      end
    
      # Access the global Knowledge Graph Search client
      kg_search = global :kg_search
    
      # Verify the request signature and return early if it failed.
      unless kg_search.signature_valid? request
        return [401, {}, ["Signature validation failed."]]
      end
    
      # Query the Knowledge Graph and format a Slack message with the response.
      # This method returns a nested hash, which the Functions Framework will
      # convert to JSON automatically.
      kg_search.make_search_request request.params["text"]
    end

    次の関数は、Slack から提供された X-Slack-Signature ヘッダーを検証することで、受信リクエストを認証します。

    Node.js

    /**
     * Verify that the webhook request came from Slack.
     *
     * @param {object} req Cloud Function request object.
     * @param {string} req.headers Headers Slack SDK uses to authenticate request.
     * @param {string} req.rawBody Raw body of webhook request to check signature against.
     */
    const verifyWebhook = req => {
      const signature = {
        signingSecret: process.env.SLACK_SECRET,
        requestSignature: req.headers['x-slack-signature'],
        requestTimestamp: req.headers['x-slack-request-timestamp'],
        body: req.rawBody,
      };
    
      // This method throws an exception if an incoming request is invalid.
      verifyRequestSignature(signature);
    };

    Python

    def verify_signature(request):
        request.get_data()  # Decodes received requests into request.data
    
        verifier = SignatureVerifier(os.environ["SLACK_SECRET"])
    
        if not verifier.is_valid_request(request.data, request.headers):
            raise ValueError("Invalid request/credentials.")
    
    

    Go

    
    // verifyWebHook verifies the request signature.
    // See https://api.slack.com/docs/verifying-requests-from-slack.
    func verifyWebHook(r *http.Request, slackSigningSecret string) (bool, error) {
    	timeStamp := r.Header.Get(slackRequestTimestampHeader)
    	slackSignature := r.Header.Get(slackSignatureHeader)
    
    	t, err := strconv.ParseInt(timeStamp, 10, 64)
    	if err != nil {
    		return false, fmt.Errorf("strconv.ParseInt(%s): %w", timeStamp, err)
    	}
    
    	if ageOk, age := checkTimestamp(t); !ageOk {
    		return false, &oldTimeStampError{fmt.Sprintf("checkTimestamp(%v): %v %v", t, ageOk, age)}
    		// return false, fmt.Errorf("checkTimestamp(%v): %v %v", t, ageOk, age)
    	}
    
    	if timeStamp == "" || slackSignature == "" {
    		return false, fmt.Errorf("either timeStamp or signature headers were blank")
    	}
    
    	body, err := io.ReadAll(r.Body)
    	if err != nil {
    		return false, fmt.Errorf("io.ReadAll(%v): %w", r.Body, err)
    	}
    
    	// Reset the body so other calls won't fail.
    	r.Body = io.NopCloser(bytes.NewBuffer(body))
    
    	baseString := fmt.Sprintf("%s:%s:%s", version, timeStamp, body)
    
    	signature := getSignature([]byte(baseString), []byte(slackSigningSecret))
    
    	trimmed := strings.TrimPrefix(slackSignature, fmt.Sprintf("%s=", version))
    	signatureInHeader, err := hex.DecodeString(trimmed)
    
    	if err != nil {
    		return false, fmt.Errorf("hex.DecodeString(%v): %w", trimmed, err)
    	}
    
    	return hmac.Equal(signature, signatureInHeader), nil
    }
    
    func getSignature(base []byte, secret []byte) []byte {
    	h := hmac.New(sha256.New, secret)
    	h.Write(base)
    
    	return h.Sum(nil)
    }
    
    // Arbitrarily trusting requests time stamped less than 5 minutes ago.
    func checkTimestamp(timeStamp int64) (bool, time.Duration) {
    	t := time.Since(time.Unix(timeStamp, 0))
    
    	return t.Minutes() <= 5, t
    }
    

    Java

    /**
     * Verify that the webhook request came from Slack.
     *
     * @param request Cloud Function request object in {@link HttpRequest} format.
     * @param requestBody Raw body of webhook request to check signature against.
     * @return true if the provided request came from Slack, false otherwise
     */
    boolean isValidSlackWebhook(HttpRequest request, String requestBody) {
      // Check for headers
      Optional<String> maybeTimestamp = request.getFirstHeader("X-Slack-Request-Timestamp");
      Optional<String> maybeSignature = request.getFirstHeader("X-Slack-Signature");
      if (!maybeTimestamp.isPresent() || !maybeSignature.isPresent()) {
        return false;
      }
    
      Long nowInMs = ZonedDateTime.now().toInstant().toEpochMilli();
    
      return verifier.isValid(maybeTimestamp.get(), requestBody, maybeSignature.get(), nowInMs);
    }

    Ruby

    # slack-ruby-client expects a Rails-style request object with a "headers"
    # method, but the Functions Framework provides only a Rack request.
    # To avoid bringing in Rails as a dependency, we'll create a simple class
    # that implements the "headers" method and delegates everything else back to
    # the Rack request object.
    require "delegate"
    class RequestWithHeaders < SimpleDelegator
      def headers
        env.each_with_object({}) do |(key, val), result|
          if /^HTTP_(\w+)$/ =~ key
            header = Regexp.last_match(1).split("_").map(&:capitalize).join("-")
            result[header] = val
          end
        end
      end
    end
    
    # This is a method of the KGSearch class.
    # It determines whether the given request's signature is valid.
    def signature_valid? request
      # Wrap the request with our class that provides the "headers" method.
      request = RequestWithHeaders.new request
    
      # Validate the request signature.
      slack_request = Slack::Events::Request.new request,
                                                 signing_secret: @signing_secret
      slack_request.valid?
    end

    Knowledge Graph API のクエリ作成

    次の関数はユーザーの検索クエリとともにリクエストを Knowledge Graph API に送信します。

    Node.js

    /**
     * Send the user's search query to the Knowledge Graph API.
     *
     * @param {string} query The user's search query.
     */
    const makeSearchRequest = query => {
      return new Promise((resolve, reject) => {
        kgsearch.entities.search(
          {
            auth: process.env.KG_API_KEY,
            query: query,
            limit: 1,
          },
          (err, response) => {
            console.log(err);
            if (err) {
              reject(err);
              return;
            }
    
            // Return a formatted message
            resolve(formatSlackMessage(query, response));
          }
        );
      });
    };

    Python

    def make_search_request(query):
        req = kgsearch.entities().search(query=query, limit=1)
        res = req.execute()
        return format_slack_message(query, res)
    
    

    Go

    func makeSearchRequest(query string) (*Message, error) {
    	res, err := entitiesService.Search().Query(query).Limit(1).Do()
    	if err != nil {
    		return nil, fmt.Errorf("do: %w", err)
    	}
    	return formatSlackMessage(query, res)
    }
    

    Java

    /**
     * Send the user's search query to the Knowledge Graph API.
     *
     * @param query The user's search query.
     * @return The Knowledge graph API results as a {@link JsonObject}.
     * @throws IOException if Knowledge Graph request fails
     */
    JsonObject searchKnowledgeGraph(String query) throws IOException {
      Kgsearch.Entities.Search kgRequest = kgClient.entities().search();
      kgRequest.setQuery(query);
      kgRequest.setKey(apiKey);
    
      return gson.fromJson(kgRequest.execute().toString(), JsonObject.class);
    }

    Ruby

    # This is a method of the KGSearch class.
    # It makes an API call to the Knowledge Graph Search Service, and formats
    # a Slack message as a nested Hash object.
    def make_search_request query
      response = @client.search_entities query: query, limit: 1
      format_slack_message query, response
    end

    Slack メッセージのフォーマット化

    最後に、次の関数は Knowledge Graph の結果をフォーマット化し、ユーザーに表示される適切な形式の Slack メッセージにします。

    Node.js

    /**
     * Format the Knowledge Graph API response into a richly formatted Slack message.
     *
     * @param {string} query The user's search query.
     * @param {object} response The response from the Knowledge Graph API.
     * @returns {object} The formatted message.
     */
    const formatSlackMessage = (query, response) => {
      let entity;
    
      // Extract the first entity from the result list, if any
      if (
        response &&
        response.data &&
        response.data.itemListElement &&
        response.data.itemListElement.length > 0
      ) {
        entity = response.data.itemListElement[0].result;
      }
    
      // Prepare a rich Slack message
      // See https://api.slack.com/docs/message-formatting
      const slackMessage = {
        response_type: 'in_channel',
        text: `Query: ${query}`,
        attachments: [],
      };
    
      if (entity) {
        const attachment = {
          color: '#3367d6',
        };
        if (entity.name) {
          attachment.title = entity.name;
          if (entity.description) {
            attachment.title = `${attachment.title}: ${entity.description}`;
          }
        }
        if (entity.detailedDescription) {
          if (entity.detailedDescription.url) {
            attachment.title_link = entity.detailedDescription.url;
          }
          if (entity.detailedDescription.articleBody) {
            attachment.text = entity.detailedDescription.articleBody;
          }
        }
        if (entity.image && entity.image.contentUrl) {
          attachment.image_url = entity.image.contentUrl;
        }
        slackMessage.attachments.push(attachment);
      } else {
        slackMessage.attachments.push({
          text: 'No results match your query...',
        });
      }
    
      return slackMessage;
    };

    Python

    def format_slack_message(query, response):
        entity = None
        if (
            response
            and response.get("itemListElement") is not None
            and len(response["itemListElement"]) > 0
        ):
            entity = response["itemListElement"][0]["result"]
    
        message = {
            "response_type": "in_channel",
            "text": f"Query: {query}",
            "attachments": [],
        }
    
        attachment = {}
        if entity:
            name = entity.get("name", "")
            description = entity.get("description", "")
            detailed_desc = entity.get("detailedDescription", {})
            url = detailed_desc.get("url")
            article = detailed_desc.get("articleBody")
            image_url = entity.get("image", {}).get("contentUrl")
    
            attachment["color"] = "#3367d6"
            if name and description:
                attachment["title"] = "{}: {}".format(entity["name"], entity["description"])
            elif name:
                attachment["title"] = name
            if url:
                attachment["title_link"] = url
            if article:
                attachment["text"] = article
            if image_url:
                attachment["image_url"] = image_url
        else:
            attachment["text"] = "No results match your query."
        message["attachments"].append(attachment)
    
        return message
    
    

    Go

    
    package slack
    
    import (
    	"fmt"
    
    	"google.golang.org/api/kgsearch/v1"
    )
    
    func formatSlackMessage(query string, response *kgsearch.SearchResponse) (*Message, error) {
    	if response == nil {
    		return nil, fmt.Errorf("empty response")
    	}
    
    	if response.ItemListElement == nil || len(response.ItemListElement) == 0 {
    		message := &Message{
    			ResponseType: "in_channel",
    			Text:         fmt.Sprintf("Query: %s", query),
    			Attachments: []attachment{
    				{
    					Color: "#d6334b",
    					Text:  "No results match your query.",
    				},
    			},
    		}
    		return message, nil
    	}
    
    	entity, ok := response.ItemListElement[0].(map[string]interface{})
    	if !ok {
    		return nil, fmt.Errorf("could not parse response entity")
    	}
    	result, ok := entity["result"].(map[string]interface{})
    	if !ok {
    		return nil, fmt.Errorf("error formatting response result")
    	}
    
    	attach := attachment{Color: "#3367d6"}
    	if name, ok := result["name"].(string); ok {
    		if description, ok := result["description"].(string); ok {
    			attach.Title = fmt.Sprintf("%s: %s", name, description)
    		} else {
    			attach.Title = name
    		}
    	}
    	if detailedDesc, ok := result["detailedDescription"].(map[string]interface{}); ok {
    		if url, ok := detailedDesc["url"].(string); ok {
    			attach.TitleLink = url
    		}
    		if article, ok := detailedDesc["articleBody"].(string); ok {
    			attach.Text = article
    		}
    	}
    	if image, ok := result["image"].(map[string]interface{}); ok {
    		if imageURL, ok := image["contentUrl"].(string); ok {
    			attach.ImageURL = imageURL
    		}
    	}
    
    	message := &Message{
    		ResponseType: "in_channel",
    		Text:         fmt.Sprintf("Query: %s", query),
    		Attachments:  []attachment{attach},
    	}
    	return message, nil
    }
    

    Java

    /**
     * Helper method to copy properties between {@link JsonObject}s
     */
    void addPropertyIfPresent(
        JsonObject target, String targetName, JsonObject source, String sourceName) {
      if (source.has(sourceName)) {
        target.addProperty(targetName, source.get(sourceName).getAsString());
      }
    }
    
    /**
     * Format the Knowledge Graph API response into a richly formatted Slack message.
     *
     * @param kgResponse The response from the Knowledge Graph API as a {@link JsonObject}.
     * @param query The user's search query.
     * @return The formatted Slack message as a JSON string.
     */
    String formatSlackMessage(JsonObject kgResponse, String query) {
      JsonObject attachmentJson = new JsonObject();
    
      JsonObject responseJson = new JsonObject();
      responseJson.addProperty("response_type", "in_channel");
      responseJson.addProperty("text", String.format("Query: %s", query));
    
      JsonArray entityList = kgResponse.getAsJsonArray("itemListElement");
    
      // Extract the first entity from the result list, if any
      if (entityList.size() == 0) {
        attachmentJson.addProperty("text", "No results match your query...");
        responseJson.add("attachments", attachmentJson);
    
        return gson.toJson(responseJson);
      }
    
      JsonObject entity = entityList.get(0).getAsJsonObject().getAsJsonObject("result");
    
      // Construct Knowledge Graph response attachment
      String title = entity.get("name").getAsString();
      if (entity.has("description")) {
        title = String.format("%s: %s", title, entity.get("description").getAsString());
      }
      attachmentJson.addProperty("title", title);
    
      if (entity.has("detailedDescription")) {
        JsonObject detailedDescJson = entity.getAsJsonObject("detailedDescription");
        addPropertyIfPresent(attachmentJson, "title_link", detailedDescJson, "url");
        addPropertyIfPresent(attachmentJson, "text", detailedDescJson, "articleBody");
      }
    
      if (entity.has("image")) {
        JsonObject imageJson = entity.getAsJsonObject("image");
        addPropertyIfPresent(attachmentJson, "image_url", imageJson, "contentUrl");
      }
    
      JsonArray attachmentList = new JsonArray();
      attachmentList.add(attachmentJson);
    
      responseJson.add("attachments", attachmentList);
    
      return gson.toJson(responseJson);
    }

    Ruby

    # This is a method of the KGSearch class.
    # It takes a raw SearchResponse from the Knowledge Graph Search Service,
    # and formats a Slack message.
    def format_slack_message query, response
      result = response.item_list_element&.first&.fetch "result", nil
      attachment =
        if result
          name = result.fetch "name", nil
          description = result.fetch "description", nil
          details = result.fetch "detailedDescription", {}
          { "title"      => name && description ? "#{name}: #{description}" : name,
            "title_link" => details.fetch("url", nil),
            "text"       => details.fetch("articleBody", nil),
            "image_url"  => result.fetch("image", nil)&.fetch("contentUrl", nil) }
        else
          { "text" => "No results match your query." }
        end
      { "response_type" => "in_channel",
        "text"          => "Query: #{query}",
        "attachments"   => [attachment.compact] }
    end

    Slack API のタイムアウト

    Slack API では、関数が Webhook リクエストを受け取ってから 3 秒以内に応答することが想定されています。

    通常、このチュートリアルのコマンドは 3 秒以内に応答します。実行時間が長いコマンドの場合、タスクキューとして機能する Pub/Sub トピックに(リクエストの response_url を含む)リクエストを push する関数を構成することをおすすめします。

    この構成によって、2 番目の関数を作成して Pub/Sub によってトリガーすることで、それらのタスクを処理し、Slack の response_url に結果を送信できます。

    Slash コマンドの使用

    1. Slack チャンネルにコマンドを入力します。

      /kg giraffe
    2. 実行した内容が完了していることをログで確認します。

      gcloud functions logs read --limit 100

    クリーンアップ

    このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

    プロジェクトの削除

    課金されないようにする最も簡単な方法は、チュートリアル用に作成したプロジェクトを削除することです。

    プロジェクトを削除するには:

    1. In the Google Cloud console, go to the Manage resources page.

      Go to Manage resources

    2. In the project list, select the project that you want to delete, and then click Delete.
    3. In the dialog, type the project ID, and then click Shut down to delete the project.

    関数の削除

    このチュートリアルでデプロイした関数を削除するには、次のコマンドを実行します。

    Node.js

    gcloud functions delete kgSearch 

    Python

    gcloud functions delete kg_search 

    Go

    gcloud functions delete KGSearch 

    Java

    gcloud functions delete java-slack-function 

    Ruby

    gcloud functions delete kg_search 

    Cloud Run functions 関数は Google Cloud コンソールで削除することもできます。