2018.02.26

Knowledge REST APIで外部サービスからナレッジを使おう

石川 良
こんにちは、エンジニアの石川です。

今回はKnowledge REST APIに関して紹介しようと思います。
最近お客様からこちらのAPIを利用して実現出来るご要望をいくつか伺う機会ありまして執筆致しました。
最近のナレッジのトピックで言えば内側に目を向けるとコンソールでの検索の利便性が向上しています。
外側に目を向けるとコミュニティで訪問者の入力内容により推奨ナレッジを表示するEinstein Answerという機能のパイロット版が追加されました。
このように機能拡張がされており、サービスを向上するにはナレッジは欠かせない存在になるのではと思っています。

Knowledge REST APIで出来ること

社内向けのナレッジを構築した後はお客様の自己解決を促すために社外向けに公開すると思います。
ただ社外向けのナレッジを構築する場合、QAサイトのコミュニティを作るだけは非常に勿体ないです！
Knowledge REST APIを利用すれば外部サイト、別システムでも使うことが出来るようになります。
※Knowledge REST APIの利用に認証は不要となっております。

それではKnowledge REST APIの中でも使うことが多そうな2つのAPIについて紹介いたします。

検索API

まずは検索用のAPIの紹介です。
こちらでSalesforceのナレッジ検索が外部システムからも使えます。

ナレッジを外部システムで利用するには単純にデータ連携するだけではまともに利用することが出来ません。
というのも検索ワードに対して必要とされるナレッジを表示できなくては使えないからです。
しかしKnowledge REST APIを利用すれば開発に時間をかけなくてもSalesforceの検索アルゴリズムを用いてナレッジが利用可能になるわけです！
具体的な利用シーンを考えると製品紹介ページに関連する補足情報を埋め込んだり、
botで受け付けたコメントに対応してナレッジを表示するという事も可能だと思います。

APIの基本的な利用方法は以下となります。
■エンドポイント
外部向けにSalesforce内のリソースを公開するのでコミュニティの設定が必要です。
コミュニティのドメイン + "/services/data/v41.0/support/knowledgeArticles"がエンドポイントになります。

■HTTP ヘッダー
Accept・・・省略可能ですが形式はapplication/json または application/xml となります。
Accept-language・・・ナレッジの言語コードを設定してください。Salesforceの日本語の文字コードは「ja」です。

■入力
string q・・・qにはSOQL,SOSLのクエリではなく検索ワードをそのまま入れてください。未入力の場合は他の条件で絞り込んだ結果が返されます。
string channel・・・App、Pkb、Csp、Prmのいずれかとなります。ナレッジレコードに設定しているチャネルが条件となります。 Appは内部アプリケーションチャネル、Prmはパートナーチャネル、Cspは 顧客チャネル、Pkbは公開知識ベースチャネルを意味します。今回は不特定多数のユーザにナレッジを見せる想定なので対象はPkbとなります。
sort・・・LastPublishedDate, CreatedDate, Title, ViewScoreのいずれかを入れてください。リファレンスに「デフォルトは LastPublishedDate で、クエリおよび検索の関連性に使用されます。」と書いてあり、ちょっとわかりづらいですが、試したところSOSLによる関連度合いでソートした順になっていました。

その他の詳細は以下をご覧ください。
https://developer.salesforce.com/docs/atlas.ja-jp.212.0.api_rest.meta/api_rest/resources_knowledge_support_artlist.htm

カテゴリAPI

カテゴリはSalesforce内ではメタデータで保持しているようでSOQLでの取得が不可能です。
もしカテゴリ構造を取得したい場合はこちらのAPIの出番となります。

APIの基本的な利用方法は以下となります。
■エンドポイント
検索のAPIと同様に外部向けにSalesforce内のリソースを公開するのでコミュニティの設定が必要です。
コミュニティのドメイン + "/services/data/v41.0/support/dataCategoryGroups"がエンドポイントになります。

■HTTP ヘッダー
Accept・・・検索APIと同様になります。
Accept-language・・・トランスレーションワークベンチを用いてカテゴリ名に翻訳を設定していると指定した言語の翻訳を取得します、未指定であればマスタ言語で出力されます。

■入力
string sObjectName・・・KnowledgeArticleVersion を固定で指定してください。
boolean topCategoriesOnly・・・trueとした場合は最上位のカテゴリのみ取得します、falseにした場合は下位の階層も取得します。

その他の詳細は以下をご覧ください。
https://developer.salesforce.com/docs/atlas.ja-jp.210.0.api_rest.meta/api_rest/resources_knowledge_support_dcgroups.htm

実際に取得すると以下のような形式になります。JSONでも取得可能です。
<dataCategoryGroups>
<categoryGroups>
<label>製品カテゴリ</label>
<name>Product</name>
<objectUsage>KnowledgeArticleVersion</objectUsage>
<topCategories>
<childCategories>
<childCategories>
<label>SkyOnDemand</label>
<name>SkyOnDemand</name>
<url>
/services/data/v41.0/support/dataCategoryGroups/Product/dataCategories/SkyOnDemand?sObjectName=KnowledgeArticleVersion
</url>
</childCategories>
<childCategories>
<label>DataSpiderCloud</label>
<name>DataSpiderCloud</name>
<url>
/services/data/v41.0/support/dataCategoryGroups/Product/dataCategories/DataSpiderCloud?sObjectName=KnowledgeArticleVersion
</url>
</childCategories>
<childCategories>
<label>DCSpider</label>
<name>DCSpider</name>
<url>
/services/data/v41.0/support/dataCategoryGroups/Product/dataCategories/DCSpider?sObjectName=KnowledgeArticleVersion
</url>
</childCategories>
<label>連携</label>
<name>Category0</name>
<url>
/services/data/v41.0/support/dataCategoryGroups/Product/dataCategories/Category0?sObjectName=KnowledgeArticleVersion
</url>
</childCategories>
<childCategories>...</childCategories>
<childCategories>...</childCategories>
<label>すべて</label>
<name>All</name>
<url>...</url>
</topCategories>
</categoryGroups>
</dataCategoryGroups>
dataCategory.xml

デモ

最後にAPIを利用したjqueryライブラリを作ったので載せておきます。

ソースコメントに補足するとsrcUrlにコミュニティのドメインとありますが、Knowledge REST APIを利用する場合はコミュニティの設定は必須となります。

処理はAPIの結果を基にリスト形式で出力するようになっています。
もし使うのであればSalesforceの静的リソースに入れて使用してください。
var KnowledgeController = KnowledgeController || {};

/**
* optionには以下を設定してください。
*
* div_id・・・リストを作成するdiv要素のID
* srcUrl・・・利用先となるコミュニティのドメイン
* number_answers・・・取得するナレッジの件数
* order・・・設定なし(関連度合い)、LastPublishedDate, CreatedDate, Title, ViewScoreのいずれか
* sort・・・ASC,DESCのいずれかデフォルトはDESC
* search・・・検索ワード（2文字以上）
* group・・・カテゴリグループのAPI名
* category・・・カテゴリのAPI名
*/
KnowledgeController.makeComponent = function(option) {
    if(!option.srcUrl){
        throw "srcURLは必須です。";
    }
    option.number_answers = option.number_answers || 5;
    //条件
    KnowledgeController.option = option;
    //検索条件を作成
    var condition = {
        pageSize: option.number_answers,
        order: option.order
    };
    if(option.sort){
        condition.sort = option.sort;
    }
    if (option.search.length >= 2) {
        condition.q = option.search;
    }
    if (option.group && option.category) {
        condition.categories = "{" + option.group + ":'" + option.category + "'}";
        condition.queryMethod = 'BELOW';
    }
    // DOM作成初期処理
    KnowledgeController.init();
    // FAQを取得
    jQuery.ajax({
        type: 'GET',
        headers: {
            'Accept-Language': 'ja'
        },
        url: option.srcUrl + '/services/data/v41.0/support/knowledgeArticles',
        data: condition,
        success: function(result) {
            KnowledgeController.createList(result.articles);
        }
    });
};

/**
 * 結果からリストを作る
 */
KnowledgeController.createList = function(articles) {
    var outKnowledgeLst = [];
    for (var i = 0; i < articles.length; i++) {
        var info = articles[i];
        outKnowledgeLst.push({
            url: KnowledgeController.option.srcUrl + '/' + info.id,
            title: info.title});
    }
    // DOM作成処理
    KnowledgeController.rendering(outKnowledgeLst);
    
};

/**
 * DOM作成処理(初期)
 */
KnowledgeController.init = function() {
    KnowledgeController.outputObj
        = jQuery(document.getElementById(KnowledgeController.option.div_id));
    KnowledgeController.outputObj.addClass('faqList');

    KnowledgeController.outputObj.append();
}

/**
 * DOM作成処理
 */
KnowledgeController.rendering = function(outKnowledgeLst) {
    var ulObj = jQuery('<ul>');
    for (var i = 0; i < KnowledgeController.option.number_answers
            && i < outKnowledgeLst.length; i++) {
        var record = outKnowledgeLst[i];
        ulObj.append(jQuery('<li>')
            .append(jQuery('<span>')
                .append(jQuery('<a>', {href: record.url}).append(record.title)))
            .append(jQuery('<br>'))
            );
    }
    KnowledgeController.outputObj.append(ulObj);    
};
faq.js
htmlはただ出力するために作ったので殺風景ですが「チョコ」に関連するナレッジをとってきています。
REST APIを呼び出すためには
・SalesforceのCORS設定に対象となる外部サイトのURLの登録
・コミュニティの設定でサポートAPIへのゲストアクセスにチェック
が必要となりますのでお忘れなく。
<!DOCTYPE html>
<html>
<head>
  <title>サンプル</title>
  <link type="text/css" rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"/>
    <script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
    <script src="コミュニティのドメイン/resource/FaqListJS" type="text/javascript"></script>

  <script>
    $(function() {
        // キーワードで表示
         KnowledgeController.makeComponent({
                div_id: 'knowledge_list'
                ,srcUrl:'コミュニティのドメイン'
                ,number_answers:5
                ,search:'チョコ'});
    });

  </script>
</head>

<body>

  <section>
    <div class="container">
      <div class="row">
        <div>
          <img src="sweets_chocolate_milk.png" class="img-fluid" width="130px">
          <h3>チョコ</h3>
          <p>100円</p>
          <p>非常に甘いです。</p>
        </div>
          <div id="knowledge_list">
            関連するナレッジ↓

          </div>            
        
      </div>
    </div>
  </section>  

</body>
</html>
index.html
実際のページを見ると関連するナレッジの部分にリスト形式でナレッジが出ていますね。

まとめ

以上がKnowledge REST APIの説明となります。
ナレッジがただの知識ベースではないことが伝われば幸いです。
18 件
    　
  • banner
  • banner

関連する記事

関連するキーワード