ささみ学習帳 - sasami's study book

ささみ学習帳

Microsoft365 や Power Platform について学んだこと・アイデアのメモ

Teams会議を作成した時に会議オプションを自動で設定するPower Automateクラウドフロー(3) - クラウドフロー編💎

 

Teams会議を作成した時に会議オプションを自動で設定するPower Automateクラウドフロー(2) - カスタムフロー編💎」の続きです。作成したカスタムコネクタを利用したフローを作成します。

 

(あらためて)今回のフローで実現できること

自分でTeams会議を新規登録した時に会議オプションを自動設定する。
会議オプションにはいろんな設定がありますので、今回はその中から共同開催者の自動設定を行います。共同開催者に誰を選定するかの条件は今回は"ランダム"です。実際運用する場合は、特定の誰かを指名できた方が使いやすいですね。

 

1.フロー全体図

 

2.フロー解説

2-1.[Office 365 Outlook] 新しいイベントが作成されたとき(V3) トリガー

  • パラメーター
    • 予定表ID
      • 主となるカレンダーを選ぶ
  • 設定
    • トリガーの条件
      • @equals(triggerOutputs()?['body/organizer'], 'xxxxxxxxx@xxxxxxxxx.com')
        • 予定の主催者が自分自身の場合のみフローが動作するように実行者のメールアドレスを指定します。
      • @equals(triggerOutputs()?['body/recurrence'], 'none')
        • 繰り返しの予定には対応しないため、繰り返しなし='none'の場合のみ起動するよう指定します。

 

2-2.[Office 365 Outlook] HTTP 要求を送信します-イベント詳細を取得

トリガーの出力にはTeams会議としての情報はさほど含まれていません。Office 365 Outlook コネクタの「HTTP要求を送信する」アクションでGraph APIを利用してイベントの詳細を取得すると、会議のURLを取得することができます。

※トリガー出力の"body"にTeams会議URLが含まれていますが、ここに含まれている会議URLが予定のTeams会議でない可能性(他社から招待されたTeams会議のURLを予定に張り付けたケースなど)も考慮してあえてAPIで確実な会議URLを取得しています。

learn.microsoft.com

 

 

2-3.[Data Control]作成-会議URL

2-2.で取得したイベントがTeams会議の場合は赤枠の部分でTeams会議URLが取得できます。

  • パラメーター
    • 入力
      • body('HTTP_要求を送信します-イベント詳細を取得')?['onlineMeeting/joinUrl']

2-4.[Control]条件-Teams会議でないorひとり会議だったら終了

いずれかの条件に該当する場合は処理を終了しています。

  • イベントがTeams会議ではない
  • ひとり会議

 

  • パラーメーター
    • Condition Expression
      • OR
      • 式1 
        • empty(body('HTTP_要求を送信します-イベント詳細を取得')?['onlineMeeting/joinUrl'])
        • is equal to
        • false
      • 式2
        • empty(body('HTTP_要求を送信します-イベント詳細を取得')?['atendees'])
        • is equals to
        • false

[False]→[Control]終了

2-5.[カスタムコネクタ]会議URLでTeams会議オプションを取得する

作成したカスタムコネクタのアクションを使って、会議URLで会議オプションを取得します。

  • パラメーター
    • フィルター式
      • JoinWebUrl eq '@{outputs('作成-会議URL')}'

 

このような形式で会議オプションが取得できます。

 

2-6.[Control]条件-会議オプションが取得できなかったら終了

何らかの要因で会議オプションが取得できない場合を想定してエラー判定を行います。

  • パラメーター
    • length(outputs('会議URLでTeams会議オプションを取得する')?['body/value'])
    • is greater than
    • 0

会議URLでTeams会議オプションを取得するアクションのbody/valueはアレイで返されますので件数が1件以上で判定しています。

[False]→[Control]終了


2-7.[Control]スコープ-参加者を抽出し選定

共同責任者に設定できない外部ゲストなどを除外した参加者の中からランダムで選択しています。

 

2-7-1.[Data Control]アレイのフィルター処理-identityProviderがAADのユーザーのみ

共同開催者に指定できないユーザーを除外するために下記フィルターを行います。

  • パラメーター
    • From
      • first(outputs('会議URLでTeams会議オプションを取得する')?['body/value'])?['participants/attendees']
    • Filter Query
      • @{item()?['identity/user/identityProvider']}
      • is equal to
      • AAD

2-7-2.[Data Control]作成-共同開催者upn

2-7-1で抽出したユーザーのリストからランダムで抽出します。

  • パラメーター
    • 入力
      • body('アレイのフィルター処理-identityProviderがAADのユーザーのみ')[rand(0,length(body('アレイのフィルター処理-identityProviderがAADのユーザーのみ')))]?['upn']

2-7-3.[Data Control]選択-attendees

出席者のjson配列を作成します。

会議オプションを更新するエンドポイントの仕様として「会議への出席者の追加や削除など、participants プロパティの出席者フィールドを調整するには、常に要求本文の出席者の完全な一覧が必要」という条件があります。

onlineMeeting を更新する - Microsoft Graph v1.0 | Microsoft Learn

この為、2-5で取得した出席者(atendees)の情報をも基に構成しています。

 

  • パラメーター
    • From
      • first(outputs('会議URLでTeams会議オプションを取得する')?['body/value'])?['participants/attendees']
    • Map
      • 1行目
        • upn
        • @{item()?['upn']}
      • 2行目
        • role
        • if(
              equals(
                  item()?['upn'],
                  outputs('作成-共同開催者upn')
              ),
              'coorganizer',
              item()?['role']
          )

 

 

2-8.[カスタムコネクタ]会議URLでTeams会議オプションを更新する

最後にカスタムコネクタのアクションで会議オプションを更新します。

  • パラメーター
    • 会議Id
      • first(outputs('会議URLでTeams会議オプションを取得する')?['body/value'])?['id']
    • Body/Participants/Attendees
      • ※アレイ全体の入力に切り替える
        •  
      • body('選択-attendees')

 

 

 

気になっている点・改善したい点

カスタムコネクタの会議オプションを取得するアクションのパラメーターを式ではなく会議URLのみを指定する形にしたかったけれど断念しました。カスタムコネクタのアクションと利用するAPIのエンドポイントのパラメータを異なる形で設定できるのだろうか🤔

 

参考にしたページ

attendeeのJSON配列を作る方法に活用させていただきました!

mofumofupower.hatenablog.com

 

 

さいごに

会議オプションを更新することは実現できたもののずいぶん大掛かりになってしまいました。

 

Teams会議を作成した時に会議オプションを自動で設定するPower Automateクラウドフロー(2) - カスタムコネクタ編💎

  • 1.カスタムコネクタで利用するGraph APIエンドポイント・リソース
    • onlineMeeting リソース
    • onlineMeetingを取得・更新するエンドポイント
  • 2.Entra ID にアプリケーション登録
  • 3.カスタムコネクタの作成
    • 3-1.全般
    • 3-2.セキュリティ
      • 3-2-1.セキュリティの設定
      • 3-2-2.コネクタを作成しリダイレクトURLをコピーする
      • 3-2-3.リダイレクトURLをEntra ID アプリケーションに反映する
    • 3-3.定義
      • 3-3-1.会議URLでTeams会議オプションを取得するアクション
      • 3-3-2.会議オプションを更新するアクション
  • 4. Power Automate から確認する
  • 5.つづきます
  • 参考にしたページ

 

こちらは「Teams会議を作成した時に会議オプションを自動で設定するPower Automateクラウドフロー(1) - 概要編💎」の続きです。

今回はGraph APIでTeams会議の会議オプションを読み書きするためのカスタムコネクタに関する記事です。

 

1.カスタムコネクタで利用するGraph APIエンドポイント・リソース

onlineMeeting リソース

Teams会議の会議オプションの情報は、Graph APIではonlineMeetingリソースとしてアクセスできるようです。

learn.microsoft.com

※リンク先は過翻訳されており一部英字表記であるべき値まで日本語化されています。英語ページと見比べて参照した方がわかりやすいかもしれません。

 

実際に取得してみるとこんな感じで会議オプションの設定値が取得できました。

 

onlineMeetingを取得・更新するエンドポイント

今回のフローで必要なonlineMeeting を取得・更新する2つのエンドポイントを使用します。

onlineMeeting を取得 GET https://graph.microsoft.com/v1.0/me/onlineMeetings?{params}onlineMeeting を更新 PATCH https://graph.microsoft.com/v1.0/me/onlineMeetings/{id}

 

onlineMeeting リソースを取得するエンドポイント

learn.microsoft.com

※リンク先は過翻訳されており一部英字表記であるべき値まで日本語化されています。英語ページと見比べて参照した方がわかりやすいかもしれません。

 

onlineMeeting リソースを更新するエンドポイント

learn.microsoft.com

※リンク先は過翻訳されており一部英字表記であるべき値まで日本語化されています。英語ページと見比べて参照した方がわかりやすいかもしれません。

 

※MicrosoftTeams コネクタに「Microsoft Graph HTTP 要求を送信する」アクションが追加されましたが、2024年3月現在の仕様では残念ながらこちらの2つは動作しません。

 

 

続きを読む

Teams会議を作成した時に会議オプションを自動で設定するPower Automateクラウドフロー(1) - 概要編💎

はじめに

今後Teamsの会議オプションがカテゴリ分けされて見やすくなるそうです!そんな訳で今回は会議オプションの使いづらい点を何とかできないかというネタです。

 

会議オプションを設定するのは…ちょっと手間

会議オプションはカテゴリで整理されるくらいに多数の設定項目があります。会議予定を登録する際に会議オプションまで設定できるのは、TeamsのデスクトップアプリまたはWebでカレンダーから会議を登録した場合に限られます(…そうですよね?)。

モバイルTeamsアプリや新しいOutlook、 私のようにサードパーティ製のスケジューラー製品を愛用している環境の場合では、予定登録後に会議オプションを設定する必要があり、忙しい時には必要な会議オプションを忘れがちです。

会議オプションの既定値を変更したりというのは標準機能ではできないようですが、Power Automate クラウドフローをつかって自分が予定を作成した時に会議オプションを自動で設定することを試みてみました。

 

必要なもの

  • Power Automate Premium等の単体ライセンス
    • カスタムコネクタを使用するため必要です
  • Entra IDへのアプリケーション登録ができるアクセス許可
    • Graph APIを利用しているため必要になります
    • 権限がない場合は管理者さんに相談が必要になります
  • カスタムコネクタにちょっとだけ慣れている
  • Graph API にちょっとだけ慣れている
  • 予定表周りをPower Automate等で操作することにちょっとだけ慣れている

 

今回のフローで実現できること

自分でTeams会議を新規登録した時に会議オプションを自動設定する。
会議オプションにはいろんな設定がありますので、今回はその中から共同開催者の自動設定を行います。共同開催者に誰を選定するかの条件は今回は"ランダム"です。実際運用する場合は、特定の誰かを指名できた方が使いやすいですね。

一例として共同開催者を設定するだけですので例えば「自動的にレコード」を必ずオンにするといった使い方もできそうです。

 

フロー全体図

今回はGraph APIを利用しますがほぼカスタムコネクタ経由となりますので、フロー自体は非常にシンプルになります。

 

フローの概要

ざっくり5つのステップです。

1.[Office 365 Outlook]新しいイベントが作成されたときトリガーでフロー開始

Office 365 Outlook コネクタの予定が登録されたことをトリガーにしてフローを開始します。

2.トリガーの出力の情報から会議URLを取得する

トリガーの出力にはTeams会議としての情報はさほど含まれていません。Office 365 Outlook コネクタの「HTTP要求を送信する」アクションでGraph APIを利用してイベントの詳細を取得すると、会議のURLを取得することができます。ただし、会議オプションの情報は含まれていませんので3の処理が必要になります。

※トリガー出力の"body"にTeams会議URLが含まれていますが、ここに含まれている会議URLが予定のTeams会議でない可能性(他社から招待されたTeams会議のURLを予定に張り付けたケースなど)も考慮してあえてAPIで確実な会議URLを取得しています。

3.会議URLをつかってカスタムコネクタ(Graph API)で会議オプションの情報を取得

今回は現状の会議出席者情報を取得しその中から共同出席者を選定するため、一旦会議オプションの情報を取得しています。

4.共同主催者を設定する

今回は、共同責任者に設定できない外部ゲストなどを除外した参加者の中からランダムで選択しているだけです。

5.カスタムコネクタ(Graph API)で会議オプションを更新する

最後に共同主催者を反映しています。

 

制限事項

「繰り返しの予定」には対応させていません

Exchange予定表の構造は非常に複雑です。繰り返しの予定にも対応させた場合に想定外の動作をする可能性がありますので、敢えて繰り返しなしの場合のみ動作するようにしています。この辺りを深く知りたい方はやまさんこちらをご覧いただくと闇が垣間見えるかと思います。

qiita.com

 

Teams会議以外の会議が混在しているケースは考慮していません

Teamsでは、Teams会議だけでなくzoom等他のオンライン会議も管理することが可能だそうですが、環境がなくどのような動作となるか未確認です。今回のフローはTeams会議のみをTeamsで管理している状態でテストしています。

 

続きます

ここから長くなりますので複数記事に分割予定です。

Teams会議を作成した時に会議オプションを自動で設定するPower Automateクラウドフロー(2) - カスタムコネクタ編💎」につづきます。

 

 

Teams のチャネルメッセージにランダムでリアクションするPower Automate クラウドフロー

(2024/3/14訂正)Xでおいしみさんに正式版Graph APIでも利用可能ということを教えていただきました!

 

 

はじめに

Teamsでメッセージにリアクションするとき既定で表示されているリアクションが無難なこともあり、いつも同じリアクションをしていませんか?

新しいTeamsでは既定のリアクションを変更できるようになりましたが、よりアグレッシブにリアクションできるようにランダムでリアクションをするフローを作成してみました。

どんなリアクションが出るかわからない新たな刺激が得られます。

 

【重要】ベータ版のAPIを利用する為運用環境での利用はお勧めしません

今回利用するGraph APIのエンドポイントは、2024年3月時点ではbetaでしか利用できません。この為今後仕様が変わったり廃止される可能性があります。

(2024/3/14訂正)Xでおいしみさんに正式版Graph APIでも利用可能ということを教えていただきました!

 

実行イメージ

 

フロー全体図

 

フロー解説

1.[Microsoft Teams]選択したメッセージの場合 (V2)

このトリガーを利用する事でメッセージの「…」からフローを実行できます。

※このトリガーを利用する場合は必ず既定の環境でフローを作成する必要があります。

  • パラメーター未設定

 

2.[変数]変数を初期化する-emoji

設定する候補の絵文字をアレイ型変数で定義します。

  • 名前
    • emoji
  • 種類
    • アレイ
    • リアクションで使いたい絵文字を↓のように記述します。
    • ["🗿","😀","😃","😄","😁","😆","😅","🤣","😂","🙂","🙃","😉","😊","😇","🥰","😍","🤩","😘","😗","☺","😚","😙","🥲","😋","😛","😜","🤪","😝","🤑","🤗","🤭","🤫","🤔","🤐","🤨","😐","😑","😶","😏","😒","🙄","😬","🤥","😌","😔","😪","🤤","😴","😷","🤒","🤕","🤢","🤮","🤧","🥵","🥶","🥴","😵","🤯","🤠","🥳","🥸","😎","🤓","🧐","😕","😟","🙁","☹","😮","😯","😲","😳","🥺","😦","😧","😨","😰","😥","😢","😭","😱","😖","😣","😞","😓","😩","😫","🥱","😤","😡","😠","🤬","😈","👿","💀","☠","💩","🤡","👹","👺","👻","👽","👾","🤖","😺","😸","😹","😻","😼","😽","🙀","😿","😾","🙈","🙉","🙊","💋","💌","💘","💝","💖","💗","💓","💞","💕","💟","❣","💔","❤","🧡","💛","💚","💙","💜","🤎","🖤","🤍","💯","💢","💥","💫","💦","💨","🕳","💬","👁️‍🗨️","🗨","🗯","💭","💤"]
    • 全ての絵文字が対応しているわけではないようです。対応していない文字を指定するとエラーが発生します。

    • 対応している絵文字の情報は見つけられませんでした。TeamsのリアクションUIで選択できる絵文字を使うのが安全でしょう。

 

3.[変数]変数を初期化する-Response

応答メッセージを格納する変数を定義します。

  • 名前
    • Response
  • 種類
    • 文字列
    • ランダムでリアクションしました!

 

4.[コントロール]条件-呼び出し元がチャットかチャネルかで分岐

呼び出し元がチャットかチャネルかで分岐します。

トリガーの出力の「チームID」の値の有無で判断します。

  • 条件
    • empty(triggerBody()?['teamsFlowRunContext']?['channelData']?['team']?['aadGroupId'])
    • 次の値に等しい
    • true

 

5.(はいの場合)変数の設定-Response

チャットから呼び出された場合は、Response変数にメッセージをセットします。

今回のフローはチャットからの呼び出しに対応しない為このメッセージを表示して終了します。

  • 名前
    • Response
    • このフローはチャネルのメッセージのみ利用できます。

 

6.(いいえの場合)[データ操作]作成-emoji count

アレイに格納された要素数をカウントしています。

  • 入力
    • add(length(variables('emoji')),-1)

 

7.(いいえの場合)変数の設定-SelectedEmoji

アレイからランダムで1文字を選択しSelectedEmoji変数に格納します。

  • 名前
    • SelectedEmoji
    • variables('emoji')[rand(0,outputs('作成-emoji_count'))]

 

8.(いいえの場合)[Microsoft Teams]Microsoft Graph HTTP要求を送信する-リアクションする

HTTP要求を送信するアクションでGraph API のsetReactionを呼び出しています。

  • URI
    • https://graph.microsoft.com/v1.0/teams/@{triggerBody()?['teamsFlowRunContext']?['channelData']?['team']?['aadGroupId']}/channels/@{triggerBody()?['teamsFlowRunContext']?['channelData']?['channel']?['id']}/messages/@{triggerBody()?['teamsFlowRunContext']?['messagePayload']?['id']}/setReaction
    • チームID,チャネルID,メッセージIDの3つのパラメーターはトリガーの出力を利用しています。
  •  メソッド
    • POST
  • 本文
    • {
        "reactionType": "@{variables('SelectedEmoji')}"
      }
  • コンテンツタイプ

 

9.[Microsoft Teams]Teamsのタスクモジュールで応答

処理結果を返します。

  • 応答のアダプティブカード
    • {
          "type": "AdaptiveCard",
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "version": "1.4",
          "body": [
              {
                  "type": "TextBlock",
                  "text": "@{variables('Response')}",
                  "wrap": true,
                  "size": "Medium"
              },
              {
                  "type": "TextBlock",
                  "text": "@{variables('SelectedEmoji')}",
                  "wrap": true,
                  "size": "ExtraLarge",
                  "horizontalAlignment": "Center"
              }
          ]
      }

 

チャネルから実行した場合

チャットから実行した場合

 

制限事項

フローの結果表示と設定される絵文字のデザインに差異があります

Teamsの絵文字とWindows/Mac等OSごとの絵文字のデザインの差異によるものです。

 

チャットメッセージへの対応について

今回利用したsetReaction, unsetReaction はチャットメッセージへのリアクションにも対応しています。しかし、Microsoft Teamsコネクタの"Microsoft Graph HTTP 要求を送信する"アクションでサポートされていない為、EntraIDへアプリケーション登録する事・HTTPコネクタ等のプレミアムコネクタが必要になります。

 

非対応絵文字を指定した場合への対処

非対応絵文字でリアクションを試みてエラーが発生した場合、絵文字を変更して再度リアクションを試みる、とした方が万全ではありますが今回はそこまで考慮していません。

 

参考にしたページ

learn.microsoft.com

 

このAPIについてはこちらでも記事にしています。

sasami-axis.hatenablog.com

 

さいごに

Microsoft Teamsコネクタに念願の "Microsoft Graph HTTP 要求を送信する"アクションが追加された事で、比較的手軽に使えるようになったので試してみました。

絵文字のアレイ化が一番大変な作業でした。

リアクション関係のAPIが正式版になった時にはもっとまじめに活用法を考えたいと思います。

 

Teams のメッセージへのリアクション をPower Automate クラウドフローで行う【チャネル限定】

(2024/3/14訂正)Xでおいしみさんに正式版Graph APIでも利用可能ということを教えていただきました!

 

  • はじめに
  • 考え方
  • 1.メッセージにリアクションする
    • アクション解説
    • 再実行することでリアクションを上書きできる
  • 2.リアクションを解除する
    • アクション解説
    • 必ず現在のリアクションを指定する必要がある
  • 3.メッセージのリアクションを取得する
    • フロー概要
    • フロー解説
  • チャットのメッセージへのリアクション
  • さいごに

 

はじめに

Power Automate クラウドフローでTeamsのチャネルのメッセージにリアクションするする方法です。

 

考え方

Power Automate のMicrosoft Teams コネクタにはリアクションするアクションは用意されていませんが、2024年3月ごろに追加された「Microsoft Graph HTTP 要求を送信する」アクションを使ってGraph APIを呼び出すことでリアクションが可能です。

  • リアクションを設定する
  • リアクションを解除する
  • メッセージのリアクションを取得する

のパターンを確認してみました。

 

【重要】ベータ版のAPIを利用する為運用環境での利用はお勧めしません

今回利用するリアクションのエンドポイントは、2024年3月時点ではbetaでしか利用できません。この為今後仕様が変わったり廃止される可能性があります。

(2024/3/14訂正)Xでおいしみさんに正式版APIでも利用可能ということを教えていただきました!

 

1.メッセージにリアクションする

Graph API の「chatMessage: setReaction」を利用します。 

learn.microsoft.com

アクション解説

[Microsoft Teams] Microsoft Graph HTTP 要求を送信する-リアクションする

  • URI
    • https://graph.microsoft.com/v1.0/teams/{teamid}/channels/{channelId}/messages/{messageId}/setReaction
    • それぞれ下記を指定します。 
      • {teamId}:チームID
      • {channelId}:チャネルID
      • {messageId}:メッセージID
  • メソッド
    • POST
  • 本文
    • 設定するリアクションをJSONで指定します。
    • {
          "reactionType": "🐈"
      }

再実行することでリアクションを上書きできる

こちらはリアクションを解除する事なく再実行で上書きする事ができます。

 

続きを読む

Open Street Map の Nominatim APIのカスタムコネクタを作成してみた💎

 

Open Street Mapとは

OpenStreetMap (OSM) は、誰でも自由に地図を使えるよう、みんなでオープンデータの地理情報を作るプロジェクトです。このプロジェクトでは、誰でも自由に参加して地図を編集し、利用することができます。

www.openstreetmap.org

 

Nominatim API とは

Nominatim APIは、そんなOpenStreetMap (OSM) のデータを利用して、場所を名前や住所で検索するためのジオコーディングAPIです。

今回はNomination API を使ってPowerPlatformのカスタムコネクタで下記を利用できるようにしてみました。

  • ジオコーディング(地名や住所から地図上の位置を取得)
  • 逆ジオコーディング(緯度経度から住所を取得)

 

必要なもの

  • Power Automate / Power Apps のPremium ライセンス
    • カスタムコネクタはMicrosoft365付属のPower Automate, Power Appsでは利用できません。Power Automate, Power Apps のPremium ライセンスなどが必要になります。

 

Open Street Map Nominatim APIを把握する

Nominatim API は利用リポリシーが定められています。誰でも自由に利用することはできますが利用ポリシーを守って利用をしましょう。

operations.osmfoundation.org

 

カスタムコネクタ化する上で必要な情報を調べる

API ドキュメントを確認し仕様を把握します。

  • 認証
    • なし
    • Nominatim APIは認証がありません。
  • httpメソッドはすべてGET
  • Search
    • https://nominatim.openstreetmap.org/search?<params>
    • キーワード検索のFree-form query と住所で検索するStructured queryがありますが、今回はFree-form queryのみ対応させます
  • Reverse
    • https://nominatim.openstreetmap.org/reverse?lat=<value>&lon=<value>&<params>

 

カスタムコネクタを作成する

個人的に使い慣れたPower Automateから作成していきます。

Power Automateにアクセスしたら「詳細」→「すべて検出」

「データ」カテゴリの中に「カスタムコネクタ」があります。

名前の横にある📌をクリックして色を反転させておくと左のメニューに表示されアクセスしやすくなります。

「カスタムコネクタ」ページにアクセスしたらページ右上の「カスタムコネクタの新規作成」→「一から作成」をクリックします。

カスタムコネクタの名前を入力して続行します。

※名前には設定できないキーワードがあります。

 

名前を設定して続行するとこのようなカスタムコネクタウィザードが表示されますので、順番に設定を行っていきます。

 

1.全般

アイコン・アイコンの背景色・説明などはお好みでいい感じのものを設定します。

 

2.セキュリティ

今回のNominatim APIは認証がありませんので設定不要です。

 

3.定義-「ジオコーディング(Serach_Freeform)」アクション

「新しいアクション」をクリックして進めます。

 

3-1.定義-「全般」の設定

Power Automate等でコネクタを使用する際に表示される動作を定義します。

  • 概要
    • ジオコーディング
  • 説明
    • テキストの説明から場所・住所を検索する
  • 操作ID
    • SearchFreeForm
    • ※内部的な識別に使われるIDです。先頭は大文字で
  • 表示
    • important
    • この設定はアクションのパラメータ設定の際の表示形式になります
      • important:既定で表示されます
      • advanced:既定では表示されず「詳細オプション」扱いになります
      • internal:ユーザーには表示されません

 

3-2.「要求」の設定

「サンプルをインポート」をクリックして設定を進めます。

このようなインポートダイアログが表示されます。

ここを設定するためには、Nominatim API のリファレンスページを参照して進めていきます。

nominatim.org

 

エンドポイントURLを参考に利用したいパラメータを"format={format}"の形式で追記してきます。今回はこのような形式で作りました。

https://nominatim.openstreetmap.org/search?q={q}&format={format}&limit={limit}&addressdetails={addressdetails}&extratags={extratags}&namedetails={namedetails}&accept-language={accept-language}&countrycodes={countrycodes}

※今回のsearchのクエリパラメータは、自由形式のクエリと構造化クエリの2種類がサポートされています。今回は自由形式のクエリの指定で作成します。

 

APIリファレンスにはemailパラメータがあり「多数のリクエストを行う場合は、適切な電子メールを含めてください」と記載があります。

利用ポリシーを確認しつつ該当しそうな場合はemailパラメータの負荷も推奨します。

 

このリファレンスページの説明を参考に、下記のように設定します。

  • 動詞
    • GET
  • URL
    • https://nominatim.openstreetmap.org/search?q={q}&format={format}&limit={limit}&addressdetails={addressdetails}&extratags={extratags}&namedetails={namedetails}&accept-language={accept-language}&countrycodes={countrycodes}

このように設定して「インポート」をクリックします。

要求の表示がこのように変わります。

クエリのパラメータを1つ1つ編集して設定を行います。

[q]

検索クエリを入力するパラメータです。

次の3か所を設定します。

  • 概要
    • 検索クエリ
  •  必須
    • はい
  • 表示
    • important

設定したら上部の「←戻る」をクリックし元のページに戻ります。

 

[format]

API応答フォーマットを指定します。カスタムコネクタで利用する場合はjson形式で出力する必要がありますので、xml形式は使用しません。

  • 概要
    • 出力形式
  • 既定値
    • jsonv2
  • 必須
    • はい
  • 表示
    • advanced
  • ドロップダウンの種類
    • 静的
    • "xml", "json", "jsonv2", "geojson", "geocodejson"

[limit]
APIの応答で返す件数の上限を設定します。

  • 説明
    • 返される結果の最大数を制限します。最大40
  • 概要
    • 制限
  • 既定値
    • 10
  • 必須
    • いいえ
  • 表示
    • advanced
  • 種類
    • integer

[addressdetails]

1を設定すると応答に住所の詳細を含まれます。

  • 説明
    • 1 に設定するとアドレスの要素への内訳が含まれます
  • 概要
    • アドレス詳細
  • 既定値
    • 0
  • 必須
    • いいえ
  • 種類
    • integer
    • 0,1

 

[extratags]

1を設定するとWikipediaのリンクや営業時間などの情報が出力されます(データが登録されている場合)

  • 説明
    • 1 に設定するとウィキペディアのリンク・営業時間などの追加情報ガ出力される
  • 概要
    •  エクストラタグ
  • 既定値
    • 0
  • 必須
    • いいえ
  • 表示
    • advanced
  • 種類
    • integer
    • 0,1

 

[namedetails]

1に設定すると名前の詳細な情報(言語ごとの表記、古い名前など)が出力されます。

  • 説明
    • 1 に設定すると結果の名前の完全なリストが含まれる。(言語のバリエーション、古い名前、参照、ブランド)
  • 概要
    • 名前の詳細
  • 既定値
    • 0
  • 必須
    • いいえ
  • 表示
    • advanced
  • 種類
    • integer
    • 0,1

[accept-language]

検索結果を表示する際の優先言語の順序。これは、次のいずれかです 言語コードの単純なコンマ区切りリスト、または同じ形式の言語コードのリスト を "Accept-Language" HTTP ヘッダーとして使用します。

  • 説明
    • 検索結果を表示する際の優先言語の順序
  • 概要
    • 表示言語の優先順序
  • 既定値
    • ja-JP,en-US
  • 必須
    • いいえ
  • 表示
    • advanced

[countrycodes]

検索結果を国コードで制限します。

  • 説明
    • 国コード(ISO 3166-1alpha2)で指定
  • 概要
    • 検索結果を国で制限
  • 既定値
    • jp
  • 必須
    • いいえ
  • 表示
    • advanced

ここまでで要求の設定はひとまず完了です。

ここが緑色のチェックに変わっていればひとまず問題ありません。

3-3.「要求」の動作確認

この状態でいったんコネクタを作成し、動作を確認してみます。
画面右上の「コネクタの作成」をクリックします。

作成に成功したら「6.テスト」をクリックします。

テストするためにはコネクタの接続が必要です。「新しい接続」をクリックします。

作成が完了するとこのように接続が選択された状態になります。

 

プロンプトを入力して「テスト操作」をクリックしてみます。

  • q
    • 富士山

 

正常に応答が返ってきた場合は「状態(200)」となります。富士山の情報が応答として返っていることが確認できます。

ここまで動作してしまえばほぼ完成です。アクションの出力の本文がJSONとして返される形で動作しますので、このまま使うこともできます。

 

3-4.定義-「応答」の設定

最後に応答の設定を行い、APIの応答を動的な値として表示されるように設定します。

まず、テスト実行した応答のボディの値をメモ帳などにコピーしておきます。

「3.定義」をクリックします。

応答-defaultをクリックします。

「サンプルからのインポート」をクリックします。

インポートダイアログが表示されます。

ここに先ほどのテスト実行の応答のボディを張り付けて「インポート」をクリックします。

 

すると本文の箇所が変化します。

※今回はaddressdetails,namedetails,extratags を1に設定して追加される値まではカバーしていません。

 

最後に「コネクタを更新」します。これで作成完了です。

 

4.定義-「逆ジオコーディング(Reverse)」アクション

手順は3と同じなのでこちらは省略気味にまとめます。 

4-1.「全般」の設定
  • 概要
    • 逆ジオコーディング
  • 説明
    • 逆ジオコーディング:緯度・経度から
  • 操作ID
    • Reverse
  • 表示
    • important

 

4-2.「要求」の設定

APIリファレンスページからURLを組み立てます。

nominatim.org

 

https://nominatim.openstreetmap.org/reverse?lat=<lat>&lon=<lon>&format={format}&addresdetails={addresdetails}&format={format}&addressdetails={addressdetails}&extratags={extratags}&namedetails={namedetails}&accept-language={accept-language}&countrycodes={countrycodes}&zoom={zoom}

これをインポートして設定します。

 

インポートしたら要求のクエリパラメーターを設定していきます。

※以降は既定値から変更したものだけ記載しています。

[lat]

  • 説明
    • 緯度(latitude)
  • 概要
    • 緯度
  • 必須
    • はい
  • 表示
    • important

[lon]

  • 説明
    • 経度(longitude)
  • 概要
    • 緯度
  • 必須
    • はい
  • 表示
    • important

[format]

API応答フォーマットを指定します。カスタムコネクタで利用する場合はjson形式で出力する必要がありますので、xml形式は使用しません。

  • 概要
    • 出力形式
  • 既定値
    • jsonv2
  • 必須
    • はい
  • 表示
    • advanced
  • ドロップダウンの種類
    • 静的
    • "xml", "json", "jsonv2", "geojson", "geocodejson"

[addressdetails]

1を設定すると応答に住所の詳細を含まれます。

  • 説明
    • 1 に設定するとアドレスの要素への内訳が含まれます
  • 概要
    • アドレス詳細
  • 既定値
    • 0
  • 必須
    • いいえ
  • 種類
    • integer
    • 0,1

[extratags]

1を設定するとWikipediaのリンクや営業時間などの情報が出力されます(データが登録されている場合)

  • 説明
    • 1 に設定するとウィキペディアのリンク・営業時間などの追加情報ガ出力される
  • 概要
    •  エクストラタグ
  • 既定値
    • 0
  • 必須
    • いいえ
  • 表示
    • advanced
  • 種類
    • integer
    • 0,1

[namedetails]

1に設定すると名前の詳細な情報(言語ごとの表記、古い名前など)が出力されます。

  • 説明
    • 1 に設定すると結果の名前の完全なリストが含まれる。(言語のバリエーション、古い名前、参照、ブランド)
  • 概要
    • 名前の詳細
  • 既定値
    • 0
  • 必須
    • いいえ
  • 表示
    • advanced
  • 種類
    • integer
    • 0,1

[accept-language]

検索結果を表示する際の優先言語の順序。これは、次のいずれかです 言語コードの単純なコンマ区切りリスト、または同じ形式の言語コードのリスト を "Accept-Language" HTTP ヘッダーとして使用します。

  • 説明
    • 検索結果を表示する際の優先言語の順序
  • 概要
    • 表示言語の優先順序
  • 既定値
    • ja-JP,en-US
  • 必須
    • いいえ
  • 表示
    • advanced

[zoom]

地図上の特定の場所に関する情報を得る際に、どの程度の詳細を求めるかを制御するために重要です。例えば、大きな地図上で国を表示したい場合はzoom=3を、特定の建物の情報が必要な場合はzoom=18を使用します。

  • 説明
    • 住所に必要なレベル(0-18)
  • 概要
    • ズーム
  • 既定値
    • 18
  • 表示
    • advanced
  • 種類
    • integer

ここまでで要求の設定は完了です。コネクタを更新して、「6.テスト」でテス操作して動作を確認します。

正常に実行できた場合"状態(200)"は、応答のボディをコピーしておきます。

例えば皇居の場合はこんな情報が返ってくるはずです。

 

4-3.「応答」の設定

4-2でテストした結果のボディのjsonを「サンプルからのインポート」でインポートし、好みで調整して完了です。

 

5.動作確認してみる

最後にPower Automateでインスタントクラウドフローを作成し動作を確認します。

作成したカスタムコネクタのアクションを追加します。

フローデザイナーでコネクタはこのように表示されます。



アクションはこのように表示されます。

 

フローにアクションを追加してみます。検索クエリに「桃太郎神社」と入れてみます。

 

次に作成アクションを追加して動的な値を表示すると設定通りに候補が表示されます。

ここではlat と lon をコンマで区切って選択しておきます。

 

フローをテスト実行してみると正常に実行され桃太郎神社の緯度・経度が取得できます。

 

参考にした情報

公式のドキュメントページのチェックは必須です。

 

nominatim.org

 

learn.microsoft.com

 

改善したいこと

  • ジオコーディング(serach)エンドポイントの構造化クエリに対応
    • Free-form query と Structured query でパラメータが排他で同時に指定するとエラーになります。カスタムコネクタ上でそのあたりを設定することができないか、が課題です。

 

さいごに

この記事はカスタムコネクタの使い方という観点では「Claude API のカスタムコネクタを作成してみた💎 - ささみ学習帳」とほぼ説明は同じです。使用するAPIのHTTP Method がPOSTかGETかで、要求をサンプルからインポートする際の手順が異なるのみです。

 

Claude API のカスタムコネクタを作成してみた💎

 

Claude3とは

GPT-4を超えた?と巷で評判のAnthropic社の生成AIサービスです。使ってみると応答の内容もありますが応答速度の速さが何より快適です。

ClaudeはREST APIで利用可能ですので、最小のシンプルな形でPowerPlatformのカスタムコネクタで利用できるようにしてみました。

 

必要なもの

  • Claude API のアカウント
  • Power Automate / Power Apps のPremium ライセンス
    • カスタムコネクタはMicrosoft365付属のPower Automate, Power Appsでは利用できません。Power Automate, Power Apps のPremium ライセンスなどが必要になります。

 

Claude APIを把握する

サインアップする

APIを利用するには、公式サイトで登録しAPIキーを取得する必要があります。APIの利用は従量課金制ですが、登録自体は無料です。また5ドル分お試し利用できる権利がついていますので登録すればとりあえず始めることができます。

https://www.anthropic.com/api

Get API Access をクリック

登録完了してサインインすると、このようなダッシュボードにアクセスできるようになります。

「Explore Documentation」からドキュメントにアクセスできます。まずここをざっと目を通しておきましょう。安心してください。日本語に対応しています。

「Start Prompting with Claude」でプロンプトを入力して試すことができるWorkbenchにアクセスできます。

「Get API Keys」こちらでからAPIキーを取得できます。

 

APIキーを取得する

ダッシュボードの「Get API Keys」をクリックします。

初回はこのような画面になりますので「Create Key」をクリックしましょう

API キーの名前をつけて「Create Key」

APIキーが作成されます。「Copy Key」をクリックしてコピーしたら安全な場所に保管しておきましょう。APIキーはこの画面でしか取得できません。一度閉じてしまうと取得できなくなりますのでご注意ください。

 

カスタムコネクタを作成する

個人的に使い慣れたPower Automateから作成していきます。

Power Automateにアクセスしたら「詳細」→「すべて検出」

「データ」カテゴリの中に「カスタムコネクタ」があります。

名前の横にある📌をクリックして色を反転させておくと左のメニューに表示されアクセスしやすくなります。

「カスタムコネクタ」ページにアクセスしたらページ右上の「カスタムコネクタの新規作成」→「一から作成」をクリックします。

カスタムコネクタの名前を入力して続行します。

※名前には設定できないキーワードがあります。

名前を設定して続行するとこのようなカスタムコネクタウィザードが表示されますので、順番に設定を行っていきます。

1.全般

アイコン・アイコンの背景色・説明などはお好みでいい感じのものを設定します。

 

2.セキュリティ

今回のClaude APIAPIキーを使用しますのでAPIキーとして設定します。

  • 認証タイプ
  • APIキー
    • パラメーターのラベル
    • パラメーター名
    • パラメーターの場所
      • ヘッダー

 

3.定義

ここで実際に使用するAPIを定義します。今回は「メッセージを作成する」アクションを1つだけ作成します。「新しいアクション」をクリックして進めます。

このよう表示に変わりますので、上から順番に設定していきます。

3-1.定義-メッセージを作成するアクション-全般

Power Automate等でコネクタを使用する際に表示される動作を定義します。

  • 概要
    • メッセージを作成する
  • 説明
    • Claudeでメッセージを生成します。
  • 操作ID
    • Message
    • ※内部的な識別に使われるIDです。先頭は大文字で
  • 表示
    • important
    • この設定はアクションのパラメータ設定の際の表示形式になります
      • important:既定で表示されます
      • advanced:既定では表示されず「詳細オプション」扱いになります
      • internal:ユーザーには表示されません

 

これらはPowerAuromate クラシックデザイナーの画面ではここに対応します

 

3-2.定義-メッセージを作成するアクション-要求

「サンプルをインポート」をクリックして設定を進めます。

このようなインポートダイアログが表示されます。

ここを設定するためには、Claude APIAPIリファレンスページを参照して進めていきます。

docs.anthropic.com

 

このリファレンスページの説明を参考に、REQUESTのサンプルを基に下記のように設定します。

  • 動詞
    • POST
  • URL
  • ヘッダー
    • Content-Type application/json
    • anthropic-version 2023-06-01
  • 本文
    • {
          "model": "claude-3-opus-20240229",
          "system": "Respond only in Japanese.",
          "max_tokens": 1024,
          "messages": [
              {"role": "user", "content": "Hello, world"}
          ],
          "temperature":0.2,
          "top_p":0.1,
          "top_k":0.1
      }
    • ※個人的好みでsystem,temperature,top_p,top_kを追加していますが、省略しても問題ありません

このように設定して「インポート」をクリックします。

要求の表示がこのように変わります。

少し設定を加えていきます。

 

[Content-Type]

ヘッダーの「Context-Type」→「編集」をクリックします。

次の3か所を設定します。

  • 既定値
  • 必須
    • はい
  • 表示
    • internal

Content-Typeは固定の値で変更する必要がありません。このように設定して、常に既定の値で設定され非表示とします。

設定したら上部の「←戻る」をクリックし元のページに戻ります。

 

[anthropic-version]

同様にanthropic-versionも設定します。

  • 概要
    • APIバージョン
  • 既定値
    • 2023-06-01
  • 必須
    • はい
  • 表示
    • important

このパラメータはAPIのバージョンを設定します。2024年3月時点の最新のバージョン2023-06-01を既定値に設定しています。

 

続いて本文を設定します。本文の「Body」→「編集」をクリックします。

次の3か所を設定します。

  • 必須
    • はい
  • 表示
    • important
  • 本文
    • 1つづつ編集画面で設定していきます
    • 設定したら上部の「←戻る」をクリックしてbodyに戻るのを繰り返します

 

[max_tokens]

生成するメッセージのトークンの最大数を指定します。最大数はモデルごとに変わる可能性がありますが、既定値として1024を仮に設定しています。使い込んでみて調整する想定です。

  • タイトル
  • 既定値
    • 1024
  • 必須
    • はい

 

[content]

所謂プロンプトをここに入力します。

  • タイトル
    • プロンプト
  • 必須
    • はい
  • 表示
    • important

[role]

  • 既定値
    • user
  • 必須
    • はい
  • 表示
    • important
  • ドロップダウンの種類
    • 静的
    • "user","assistant"

[model]

Claudeのモデルを選択します。Claude3は現在2つのモデルが選べるようです。

  • claude-3-opus-20240229
  • claude-3-sonnet-20240229

 

  • タイトル
    • モデル
  • 既定値
    • claude-3-sonnet-20240229
  • 必須
    • はい
  • 表示
    • important
  • ドロップダウンの種類
    • 静的
    • "claude-3-sonnet-20240229","claude-3-opus-20240229"

[system]

Claudeの応答を制御するシステムメッセージを設定します。今回は既定値で必ず日本語で返す既定値を設定します。

  • タイトル
    • システムメッセージ
  • 既定値
    • Respond only in Japanese.
  • 表示
    • advanced

[temperature],[top_p],[top_k] 

これら3つは表示のみ設定します。

  • 表示
    • advanced

ここまでで要求の設定はひとまず完了です。

ここが緑色のチェックに変わっていればひとまず問題ありません。

3-3.定義-メッセージを作成するアクション-要求の動作確認

この状態でいったんコネクタを作成し、動作を確認してみます。
画面右上の「コネクタの作成」をクリックします。

作成に成功したら「6.テスト」をクリックします。

テストするためにはコネクタの接続が必要です。「新しい接続」をクリックします。

Webブラウザの新しいタブで接続を追加するページが表示されます。あらかじめ保管しておいたCloude APIキーを張り付けて「接続の作成」をクリックします。

元のタブに戻り、接続の右の矢印アイコンで更新すると作成した接続が表示されます。

プロンプトを入力して「テスト操作」をクリックしてみます。

  • content
    • 日本で一番高い山は?

正常に応答が返ってきた場合は「状態(200)」となります。
入力したプロンプトに対して富士山を期待した応答ができていることが確認できます。

ここまで動作してしまえばほぼ完成です。アクションの出力の本文がJSONとして返される形で動作しますので、このまま使うこともできます。

 

3-4.定義-メッセージを作成するアクションの応答

最後に応答の設定を行い、APIの応答を動的な値として表示されるように設定します。

まず、テスト実行した応答のボディの値をメモ帳などにコピーしておきます。

{
  "id": "msg_01DKQt2hi47bbM7BfHuCovdK",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "日本で一番高い山は富士山です。富士山の標高は3,776メートルです。富士山は静岡県と山梨県の県境にある成層火山で、その美しい形状から「富士」という名前が付けられました。山頂には深さ約200mの火口があり、火山活動は現在も続いています。古くから日本人に親しまれ、芸術の題材にもなっている国民的な名峰です。"
    }
  ],
  "model": "claude-3-sonnet-20240229",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 24,
    "output_tokens": 138
  }
}

 

「3.定義」をクリックします。

応答-defaultをクリックします。

「サンプルからのインポート」をクリックします。

インポートダイアログが表示されます。

ここに先ほどのテスト実行の応答のボディを張り付けて「インポート」をクリックします。

すると本文の箇所が変化します。

JSONの構造がそのまま設定されていますので、このまま不要なものまで動的な値として表示されてしまいます。

1つづつ設定していきます。

[text]

応答テキストです。

  • タイトル
    • 応答テキスト
  • 表示
    • important

[stop_reason]

停止理由はエラー処理のために使いそうなので表示されるように設定しておきます。

"end_turn": モデルは自然な停止点に到達しました
"max_tokens": 要求を超えましたmax_tokensまたはモデルの最大値
"stop_sequence": 提供されたカスタムの 1 つstop_sequences生成されました

  • タイトル
  • 停止理由
  • 表示
  • important

[type],[id],[model],[stop_sequence],[type],[input_tokens],[top_tokens]

その他は動的な値として必要ないのでinternalにして非表示とします。

最後に「コネクタを更新」します。これで作成完了です。

 

4.動作確認してみる

最後にPower Automateでインスタントクラウドフローを作成し動作を確認します。

作成したカスタムコネクタのアクションを追加します。

フローデザイナーでコネクタはこのように表示されます。

アクションはこのように表示されます。

フローにアクションを追加してみます。

「Add new item」をクリックすることで複数のメッセージが設定できます。

※Roleの既定値に"user"を設定したのですが反映されませんでした。ひとまず"user"と入力しておきます。

プロンプトを設定しておきます。

次に作成アクションを追加して動的な値を表示すると設定通りに候補が表示されます。

ここではbody/contentを選択しておきます。

フローをテスト実行してみると正常に実行されClaudeの応答が取得できます。

クラシックデザイナーでもこのように表示されます。

 

参考にした情報

公式のドキュメントページのチェックは必須です。

docs.anthropic.com

 

learn.microsoft.com

 

今後の課題

 

さいごに

リファレンスページを見ながらメッセージ作成のみ作ってみました。OpenAI APIやAOAIに近いJSONの構造ですので、それらを使ったことがある方であれば比較的容易に使えそうです。