リソース
Micetro REST API の概要 (v25.1+)

Micetro REST API の概要 (v25.1+)

DNS、DHCP、およびIPアドレス管理のあらゆる側面を自動化・統合する

BlueCat white paper cover introducing Micetro REST API v25.1+ for DNS, DHCP, and IP address management

主なポイント

このホワイトペーパーは、BlueCat Micetro REST API（v25.1+）の構造、使用パターン、運用ベストプラクティスを解説し、DNS、DHCP、IPアドレス管理（DDI）をプログラムで自動化・統合する方法を示します。APIは単一の統合コントロールプレーンを提供し、Microsoft、BIND、Kea、Cisco、クラウド、BlueCatアプライアンスにまたがるリソースを標準的なHTTPメソッドと豊富なクエリパラメータで操作できるため、CI/CDやITSMとの連携や一括操作、変更監査を可能にします。ドキュメントは認証フロー（ベアラートークン推奨）、Postman/OpenAPIの利用、PowerShell/Pythonのサンプル、ベストプラクティス（最小権限、トークン管理、一括処理の分割、エラー処理、監査）など、実運用での導入・運用・トラブルシューティングに役立つ具体的手順を提供します.

Micetro REST API に推奨される認証方式は何で、運用での注意点は何ですか？

推奨される認証方式はセッションベースのベアラートークンです。セッショントークンは /sessions などのエンドポイントから取得し、以降のすべてのAPIリクエストで Authorization: Bearer ヘッダーとして使用します。運用上はトークンをコードにハードコーディングしないこと、環境変数やセキュアなシークレット保管庫に保存すること、トークンの寿命を短く保ち定期的にローテーションすること、そして異なる環境間で同一トークンを再利用しないことが強調されています。また、Windowsドメイン環境では NTLM/Kerberos がサポートされ、基本認証はレガシー方式として存在するが自動化用途では推奨されません。

大規模なデータセットを API で扱うときの効率的な取得と一括処理のベストプラクティスは何ですか？

大規模データセットでは必ずクエリパラメータの limit と offset を使ってページングし、例えば 100 件ずつのチャンクで処理することが推奨されています。filter、sortBy、sortOrder、targetRef といったパラメータを組み合わせて必要なサブセットだけを取得し、帯域幅とメモリ使用を最小化してください。dnsrecords や ranges、ipamrecords のような一括リソースエンドポイントは一度の POST で複数オブジェクトを処理できますが、部分的な失敗に対処するためにレスポンス内の成功/失敗情報を解析し、ジョブを小さなトランザクションに分割して再試行やロールバック処理を組み込むことがベストプラクティスです。

Micetro API を安全かつ可観測に運用するための監査とエラー処理に関する推奨事項は？

変更のトレーサビリティ確保のためにカスタムプロパティや /history エンドポイントを活用して操作履歴と所有権情報を保存・照会することが推奨されています。エラー処理では常にHTTPステータスコードを確認し、返される構造化JSONのエラーコードとメッセージを解析して適切にログとアラートを残してください。リクエスト送信前にローカル検証（IP形式、プロパティ型など）を行い、失敗時は完全なリクエスト/レスポンス詳細を監査記録として保存します。さらに、APIアクセスログと認証失敗の試行を定期的にレビューし、最小権限の原則に従ってロールを管理し、セキュリティとコンプライアンスを維持してください。

Contents

エグゼクティブサマリー
はじめに
- APIエンドポイント：
- 環境に関する注意事項：
認証
- セッショントークンの取得方法：
- その他、サポートされている認証方法：
サポートされているHTTPメソッド
トップレベルのAPIリソースまたはオブジェクト
リソースの操作
- リソースのパスと識別子
- 一般的なクエリパラメータ
クエリパラメータの使用タイミングと方法
ヒント、パターン、および高度な使い方
自動化とトラブルシューティングの例
ベストプラクティス
Postman の使用方法とワークフロー
PowerShell のスクリプト例
Pythonのスクリプト例
主な追加リソース

エグゼクティブサマリー

ネットワークがますますハイブリッド化、分散化、自動化されるにつれ、DNS、DHCP、およびIPアドレス管理（総称してDDIと呼ばれる）システムをプログラムで管理する能力は、企業全体での俊敏性と一貫性を維持するために不可欠です。 BlueCat Micetro REST API は、単一の統合されたコントロールプレーンを通じて、Microsoft、BIND、Kea、Cisco、クラウドプラットフォーム、および BlueCat アプライアンスにまたがる DDI インフラストラクチャのあらゆるコンポーネントを自動化およびオーケストレーションするための、標準ベースの統一されたインターフェースを提供します。

APIファーストのプラットフォームとして構築されたMicetroは、ほぼすべてのDDI機能をRESTエンドポイントを通じて公開しており、ネットワーク管理者やDevOpsチームは以下のことが可能になります：

反復的なタスクやワークフローを自動化する
エンタープライズ向け自動化フレームワーク、CI/CDパイプライン、およびITサービス管理システムとの連携
変更の監査とコンプライアンスの徹底
クラウドおよびハイブリッド環境にわたるサービスのオーケストレーション

管理対象のすべてのDDIオブジェクトを、標準的なHTTPメソッドを通じてアクセス可能なリソースとして扱うことで、このAPIは複雑な管理タスクを簡素化し、変更ワークフローを迅速化し、環境全体での設定の一貫性を確保します。

このホワイトペーパーでは、Micetro REST APIの構造、使用パターン、および運用上のベストプラクティスについて、実践的な概要を解説します。ネットワークエンジニア、DevOpsチーム、システムインテグレーター向けに設計されたMicetroのAPIは、Microsoft、BIND、Kea、Cisco、およびクラウド環境にわたるDDI運用を自動化、オーケストレーション、統合することができます。本ホワイトペーパーでは、PowerShell や Python などのスクリプト言語を使用したり、エンタープライズ自動化フレームワークと統合したりすることで、チームが Micetro の自動化機能をどのように拡張できるかを解説します。

本資料には、自動化、トラブルシューティング、およびワークフロー開発におけるAPIの使用方法を説明する実践的な例が含まれています。OpenAPI仕様をPostmanにインポートして探索やテストを行うためのステップバイステップのガイダンスに加え、PowerShellおよびPythonのサンプルスクリプトも提供しています。最後のセクションでは、Micetroに関する理解を深め、自動化の取り組みを加速させるための重要な追加リソースを一覧で紹介します。

はじめに

Micetroは、DDIのあらゆる側面を自動化および統合するための、堅牢かつ最新のREST APIを提供しています。このREST APIは、DDI環境への機能豊富で安全かつスケーラブルなアクセスを提供します。これは、あらゆる自動化および統合タスクに最適なインターフェースであり、あらゆる規模のネットワークチームにおける日常的なワークフローから高度なカスタム自動化シナリオまでをサポートします。統合の構築、日常的な運用スクリプトの作成、あるいはネットワークリソースのライフサイクル全体管理のいずれにおいても、Micetro REST APIは、今日のハイブリッド環境、マルチクラウド環境、およびコンプライアンス重視の企業に必要な柔軟性とパワーを提供します。

APIエンドポイント：

ベースURL：https://<micetro.yourdomain.tld>/mmws/api/v2/
インタラクティブな Swagger ドキュメント:https://<micetro.yourdomain.tld>/mmws/api/doc/
OpenAPI (Swagger) のダウンロード：https://<micetro.yourdomain.tld>/mmws/api/swagger.json

APIドキュメントとスキーマは、これらのURLで常に最新の状態に保たれています。また、Postmanやその他のAPIツールにインポートして、探索やワークフローのテストを行うこともできます。

環境に関する注意事項：

このドキュメントに記載されているすべての POSIX 形式のサンプルは、Ubuntu 24.04 LTS 上で、システムに標準で搭載されている curl および標準の OpenSSL ライブラリを使用して検証されています。お使いの環境は異なる場合があります。オペレーティングシステム、Micetro のバージョン、API URL、TLS 設定、証明書の信頼性、認証設定などの変数に応じて、サンプルコマンドの調整が必要になる場合があります。

たとえば、自己署名証明書を使用している環境では、テスト中に厳格な TLS 検証をバイパスするために、curl -k（非セキュアモード）の使用が必要になる場合があります。このフラグは、管理された非本番環境でのみ使用してください。

認証

REST API での推奨される認証方法は、ベアラートークン（セッションベース）によるものです。ベアラートークンは、対話型での使用と自動化の両方において、最も安全かつ柔軟なアプローチです。これにより、API 呼び出しのたびに認証情報を埋め込む必要がなくなり、セッションのタイムアウトやきめ細かな権限制御が可能になります。

セッショントークンの取得方法：

cURL command example creating BlueCat API session with JSON username and password

返されるJSONにはセッショントークンが含まれています。このトークンを、以降のすべてのAPIリクエストの認証ヘッダーにおいてベアラートークンとして使用してください：

セキュリティに関する注意：コードにパスワードを埋め込んだり、ログでセッショントークンを共有したりしないでください。実際の自動化では、常に環境変数またはセキュアな保管庫を使用してください。

その他、サポートされている認証方法：

NTLM または Kerberos — Windows ドメインメンバーサーバーに Micetro Central がインストールされているオンプレミス環境または Windows Active Directory (AD) 環境向け。
レガシー — 基本認証はサポートされていますが、自動化やスクリプトでの使用は推奨されません。

サポートされているHTTPメソッド

RESTでは、リソースが中心となります。リソースはURLで指定し、HTTPメソッドを使用してそのリソースに対して操作を実行します。

以下の表に示すように、最も一般的な4つのHTTPメソッドは、GET、PUT、POST、およびDELETEです

Method	Description
GET	Retrieve resources and object details (read-only operations)
POST	Create resources or trigger specific server-side operations
PUT	Update resources (entire object or specific properties)
DELETE	Remove resources from the system

多くのエンドポイントでは、一括作成、一括更新、および特殊な操作（監査ログのクエリ、DNSレコードの一括追加など）といった高度な操作がサポートされています。各リソースのAPIドキュメントを参照してください。

トップレベルのAPIリソースまたはオブジェクト

以下の表は、小文字および複数形の名付け規則を用いた、すべての主要なREST APIリソースエンドポイントを一覧表示しています。各エンドポイントは、Micetroにおける主要なオブジェクトタイプまたはシステム機能へのアクセスを提供します。

Resource	Description
adForests	AD forests
adSiteLinks	AD site link
adSites	AD sites
addressSpaces	Organizations
appliances	Appliances
changeRequests	Change requests
cloudNetworks	Cloud networks

Resource	Description
cloudServiceAccounts	Cloud integration
devices	Connectable devices
dhcpAddressPools	DHCP address pools
dhcpExclusions	DHCP exclusions
dhcpGroups	DHCP groups
dhcpReservations	DHCP reservations
dhcpScopes	DHCP scopes
dhcpServers	DHCP servers
dhcpSuperscopes	DHCP superscopes
dnsRecords	DNS records
dnsServers	DNS servers
dnsViews	DNS views
dnsZones	DNS zones
folders	Folders for objects and custom filters
groups	User groups
interfaces	Device interfaces
ipamRecords	IP address management (IPAM) records
micetro	General Micetro system information
ranges	IP address ranges
reportDefinitions	Report definitions
reportSources	Report sources
reports	Reports
roles	User and group roles
users	User administration

各リソースで利用可能なメソッド、データモデル、パラメータの詳細については、/mmws/api/doc/ のインタラクティブな API ドキュメント、または https://api.menandmice.com/ をご覧ください。

リソースの操作

Micetro REST API の文脈において、リソースとは、DNS ゾーン、DHCP スコープ、IP アドレス、ユーザー、サーバーなど、Micetro システム内で管理可能なあらゆるオブジェクトまたはエンティティを指します。各リソースは、DDI インフラストラクチャの具体的なコンポーネントに対応しており、API を通じてプログラム的にアクセスおよび操作することができます。

リソースは、Micetro API の設計の基盤です。すべての REST エンドポイントはリソースを中心に構成されており、一意の URL で識別され、標準的な HTTP メソッドを使用してアクセスされます。各リソースタイプはパスごとにグループ化され、各リソースには一意の参照識別子が割り当てられています。

リソースのパスと識別子

APIリソースのパスは、/mmws/api/v2/<resource> という形式になります（例：/mmws/api/v2/dnszones）。
各オブジェクトには一意の ref 文字列（例：dnsZones/12345）があります。ほとんどのエンドポイントでは、この ref、一意の名前、または数値 ID のいずれかを使用してオブジェクトを参照できます。迷った場合は、常に ref を使用してください。
多くのエンドポイントは階層構造になっています（例：DNSレコードはゾーンに属します：/dnszones/<zone-ref>/dnsrecords）。

一般的なクエリパラメータ

Micetro REST API は、検索、フィルタリング、並べ替え、結果のページネーションを行うための豊富なクエリパラメータを提供しており、効率的なデータ取得を可能にし、帯域幅の使用を最小限に抑えます。

Parameter	Type	Purpose and example
filter	string	Filter results on properties. Flexible, supports logical/comparison/set operators. Example: `filter=name~^corp AND type=A`
sortBy	string	Sort results by a property. Most often name, created, lastModified, or a custom property. Example: `sortBy=name`
sortOrder	string	Sort direction, either ascending (default) or descending. Example: `sortOrder=Descending`
offset	integer	Skip a certain number of records for pagination. Example: `offset=50`
limit	integer	Return a maximum number of records. Example: `limit=100`
pretty	bool	Pretty-print (indented) JSON for human reading. Not needed in automation. Example: `pretty=true`
targetRef	string	Get a page of results where the specified object appears first (useful for UI-driven automation).

クエリパラメータの使用タイミングと方法

filter

目的：条件に一致するサブセットに結果を絞り込むこと。関連データのみを処理すべきレポート、ダッシュボード、または自動化に最適です。
構文のハイライト：シンプル：name=corp.com。
正規表現: name~prod-
論理演算子：AND、OR、NOT（例：type=A OR type=CNAME）
設定：{A,CNAME} を入力してください
否定：type!=A または NOT type=A
ネスト: (name~”dev- AND type=A) または (name~”prod- AND type=CNAME)

sortBy および sortOrder

目的：予測可能な結果、ユーザーフレンドリーなUI、および効率的なページングを実現するための順序制御。
使用方法：任意の単純プロパティ、カスタムプロパティ、さらには計算フィールドや派生フィールドでもソート可能です（ドキュメントを参照）。
デフォルト：設定されていない場合、デフォルトの並べ替え順序はエンドポイントによって異なります（多くの場合、名前または作成日順）。
例：最も最近更新されたDNSゾーンを取得する：

Terminal curl command calling BlueCat API to list mDNS nodes sorted by last modified date

オフセットと制限

目的：大規模な結果セットをページ単位で表示するため。結果リストに上限がない場合は、常に limit を使用してください。
ベストプラクティス：スクリプトや自動化処理では、メモリやタイムアウトの問題を防ぐため、結果を常に小分け（例：100件ずつ）にして処理してください。
例：大規模なレコードセットから201～300番目のレコードを取得する場合：

Curl command example calling BlueCat DNS zones API with bearer token and pagination parameters

targetRef

目的：特定のオブジェクトをページングのアンカーとして設定します。これは、UIベースのワークフローや照合ツールにおいて、一貫性のあるナビゲーションを行う際に役立ちます。
例：特定のレコードが先頭に表示される結果ページを取得する（使用方法についてはドキュメントを参照）。

pretty

目的：探索時の可読性を高めるため。本番環境の自動化ではほとんど使用されません。
例：

curl command snippet showing Authorization Bearer token header syntax on dark terminal background

ヒント、パターン、および高度な使い方

組み込みフィールドと同様に、カスタムプロパティでフィルターを使用する：filter=CustomTag=Finance
クエリパラメータの組み合わせ：例）?filter=name=corp&sortBy=lastModified&limit=25
一括リソースAPI（DNSレコード、範囲など）は、複数のオブジェクトを対象とした自動化のためにフィルタリングが可能です。
多くのリソースクエリは大文字と小文字を区別します。各リソース固有の詳細については、APIドキュメントを確認してください。
リソース固有のフィルター（例：dnsrecordsはタイプ、データ、TTLなどをサポート）により、極めて的を絞った検索が可能になります。
バッチ自動化スクリプトの作成や、大規模なデータセットの取得を行う際は、常に limit と offset を使用してください。
最も高度な用途向けに、ネストされた複雑なブール式フィルターがサポートされています。詳細はSwaggerおよびOpenAPIの例を参照してください。

自動化とトラブルシューティングの例

以下の例では、Curl および API を使用した、実運用におけるさまざまな自動化およびトラブルシューティングのシナリオを示しています。さらに多くの例については、以下のスクリプト作成に関するセクションを参照してください。

すべてのDNSサーバーを一覧表示する

Terminal curl command using bearer token to query BlueCat MMv3 dnsServers API endpoint

XML出力の要求（JSONの代わりに）

cURL command example calling BlueCat DNS servers API with authorization bearer token and XML accept header

ゾーン内の「vm」で始まるAレコードを一覧表示する

Example curl command calling BlueCat DNS records API with authorization header and URL filter parameters

DNSレコードを追加する

Curl command creating an A DNS record via BlueCat DNS records API with JSON payload

複数のタイプによる高度なフィルタリング

Curl command example querying BlueCat MMS DNS records API with authorization header and filter parameters

DNSレコードの一括作成

Example curl command posting DNS A records to BlueCat dnsRecords API endpoint

DNSゾーンのイベント履歴を取得する

curl command calling BlueCat MMS API to retrieve dnsZones history with authorization bearer token

カスタムプロパティ（プロパティ定義）の作成<h3 class=”wp-block-heading” id=”get-all-dhcp-scopes-

cURL POST request example creating a property definition with authorization header and JSON body

すべてのDHCPスコープを取得（DHCPサーバー順に並べ替え）

Curl command using bearer token to query DNS ranges API endpoint with fnthoServerRef parameter

スコープのすべてのDHCPリースを取得する

curl command using bearer token to request leases from BlueCat API endpoint

カスタムプロパティによるフィルタリング

Terminal snippet showing curl command with HTTP Authorization Bearer token header

Code snippet showing an MMSP API endpoint URL with datacenter-1 location filter

クエリパラメータの組み合わせ

curl command example querying BlueCat MMS DNS zones API with authorization header and filtering parameters

ベストプラクティス

このセクションでは、Micetro REST API を基盤とした統合機能の設計、自動化、およびセキュリティ確保に関するベストプラクティスを推奨します。この API は DNS、DHCP、および IP アドレス管理リソースへの完全なプログラムによるアクセスを提供するため、信頼性、セキュリティ、および保守性を高める一貫した基準に従うことが不可欠です。以下のガイドラインでは、カスタムプロパティ、ロールベースのアクセス制御、一括操作、変更履歴、エラー処理、セキュリティといった主要な運用分野に焦点を当て、スクリプトや統合がMicetroとの安全かつ効率的な連携を実現するための実証済みのパターンに従うよう支援します。

カスタムプロパティ

/propertydefinitions エンドポイントを使用して、ビジネスまたは技術的なメタデータ（例：資産所有者、環境、場所、コストセンター）のためのオブジェクト上のカスタムフィールドを定義および管理します。
トレーサビリティとレポート作成のために、自動化の状態、変更履歴、所有権タグをカスタムプロパティとして保存します。
レポートやスクリプトでカスタムプロパティフィルターを使用する: filter=owner=devops
社内APIスタイルガイドにカスタムプロパティの名前と型を記載してください。

ロールベースのアクセス制御

すべてのリソースはきめ細かな権限設定に対応しており、ゾーン、範囲、グループなどに対してアクセス権を付与できます。
/access エンドポイントを使用して、任意のユーザーまたはグループの権限を監査および管理します。
すべてのAPIユーザーに対して常に最小権限の原則を適用してください（必要な場合を除き、自動化処理で管理者トークンを使用しないでください）。
（/roles 経由で作成された）ロールを使用して、実際のチームや機能に基づいたアクセス権を表現します。
役割の割り当てをローテーションし、機密性の高い変更がないか監査ログを定期的に確認してください。

一括操作

dnsrecords、ranges、ipamrecords などのエンドポイントは、一括作成または一括更新に対応しています。速度と効率性を高めるため、1回のPOSTリクエストで複数のオブジェクトを送信できます。
一括操作では、オブジェクトごとの成功または失敗を含む構造化された応答が返されます。自動化処理では、常にエラーを解析し、報告してください。
limit および filter を使用して、大規模なジョブをより小さく、信頼性の高いチャンクに分割します。
一括更新は、オンボーディング、移行、およびコンプライアンス対応に最適です。

履歴

イベント履歴エンドポイント（例：/history）を使用して、リソースに加えられたすべての変更を照会したり、時間の経過に伴うユーザーのアクションを監査したりできます。

エラー処理

すべてのエラー応答は、コードとメッセージを含む構造化されたJSON形式です（一覧についてはAPIドキュメントを参照してください）。
堅牢な処理を行うためには、自動化処理では常にHTTPステータスコードを確認し、エラーJSONを解析する必要があります。
リクエストを送信する前に、すべてのデータをローカルで検証する（例：IPアドレスの形式、プロパティタイプ）。
監査およびトラブルシューティングのために、完全なリクエストおよびレスポンスの詳細を含むエラーをログに記録します。
一括処理では、部分的な失敗と完全な失敗の両方を適切に処理します。

セキュリティ

短命なセッショントークンを使用し、それらを環境変数またはシークレット保管庫に保存し、決してハードコーディングしないでください。
サービスアカウントのパスワードまたはトークンは定期的に更新し、環境間（例：開発環境と本番環境）でトークンを再利用しないでください。
APIユーザーアカウントの権限と適用範囲を、必要最小限に制限する。
API アクセスログと認証失敗の試行を定期的に確認してください（/history および管理コンソールを参照）。
すべてのAPI呼び出しでHTTPSエンドポイントを優先し、証明書を検証します。
すべての永続的な自動化において、セッションまたはトークンの有効期限チェックを自動化します。

Postman の使用方法とワークフロー

Micetro REST API は、OpenAPI（Swagger）仕様を通じて完全にドキュメント化されており、Postman などのツールに直接インポートして、インタラクティブな探索やワークフローの自動化を行うことができます。このセクションでは、API 定義の読み込み方法、Postman 環境の設定方法、およびセッショントークンを使用した認証ワークフローの設定方法について説明します。これらの手順に従うことで、エンドポイントのテスト、認証済みリクエストの連鎖、および一括更新や変更リクエストなどの一般的な自動化シナリオの管理を行うための、すぐに使える完全なワークスペースが提供されます。Postmanコレクションを最新のMicetro OpenAPI仕様と同期させておくことで、統合が正確かつ効率的であり、現在のAPIスキーマと整合していることを保証できます。

APIのインポート

OpenAPI/Swagger仕様をダウンロード：https://<micetro>/mmws/api/swagger.json
完全かつ最新のエンドポイントおよびスキーマのリファレンスについては、Postmanにコレクションとしてインポートしてください。
以下の変数を使用して環境を作成または設定します：

Code snippet defining BlueCat API base URL and session token variables in a dark themed editor

ワークフローでのPostmanの使用

ログインワークフロー：テストスクリプトまたは環境変数を使用して、/sessions への POST リクエストを作成し、レスポンスから {{token}} を設定します。
リクエストの連鎖：Postmanの環境設定を使用して、すべてのリクエストのヘッダーに「Authorization: Bearer {{token}}」を自動的に設定します。
コレクションと自動化：フォルダを使用してワークフローをグループ化します（例：「DNSレコード」、「一括操作」、「変更リクエスト」）。頻繁に使用するフィルターや一括更新を、再利用可能なリクエストとして保存します。
一括インポートとテスト：Micetroの新しいリリースごとに、SwaggerまたはOpenAPIを直接インポートして

例：Postmanトークンの自動取得（テストスクリプト）

JavaScript snippet in Postman scripts tab to parse response and save session bearer token variable

その後、以降のリクエストでは、次の変数を使用します：Authorization: Bearer {{bearerToken}}

PowerShell のスクリプト例

PowerShell などのスクリプト言語を使用することで、Micetro REST API とのやり取りを強力かつ柔軟に自動化できます。PowerShell を使用することで、管理者や DevOps チームは、繰り返し可能なワークフローをスクリプト化したり、Micetro データをより広範な IT 自動化フレームワークに統合したり、手作業を最小限に抑えながら DNS、DHCP、IP アドレス管理リソースにわたる複雑な操作を実行したりすることができます。 PowerShellはRESTfulリクエスト、JSONの解析、および安全な認証情報の処理をネイティブにサポートしているため、一括更新、スケジュールされたレポート作成、あるいはMicetroと他のシステムやサービスパイプラインとの統合など、信頼性の高い本番環境レベルの自動化を構築するのに最適です。以下に、PowerShell 内で Micetro API を使用して認証を行い、レコードを追加し、エラーを処理する方法の基本的な例を示します。