AppDynamics API Clientの設定およびトラブルシューティング

はじめに

このドキュメントでは、AppDynamics APIクライアントの作成、トークンの生成、および問題のトラブルシューティングを行う方法について説明します。

前提条件

要件

次の項目に関する知識があることが推奨されます。

• APIクライアントを作成するには、ユーザーにアカウント所有者（デフォルト）の役割、または管理、エージェント、ウィザードの開始アクセス許可を持つカスタムの役割が必要です。

使用するコンポーネント

このドキュメントの情報は、次のソフトウェアとハードウェアのバージョンに基づいています。

• AppDynamicsコントローラー

このドキュメントの情報は、特定のラボ環境にあるデバイスに基づいて作成されました。このドキュメントで使用するすべてのデバイスは、クリアな（デフォルト）設定で作業を開始しています。本稼働中のネットワークでは、各コマンドによって起こる可能性がある影響を十分確認してください。

背景説明

このドキュメントでは、Representational State Transfer(REST)およびアプリケーションプログラミングインターフェイス(API)の呼び出しを使用して、AppDynamicsコントローラーからデータに安全にアクセスするためのAPIクライアントを作成するプロセスについて説明します。APIクライアントは、オープン認証(OAuth)トークンベースの認証を利用します。OAuthを使用すると、サードパーティのサービスは、ユーザクレデンシャルを公開せずにエンドユーザアカウント情報にアクセスできます。このサービスは仲介として機能し、特定のアカウント情報の共有を許可するアクセストークンをサードパーティサービスに提供します。APIクライアントの設定後、ユーザーはOAuthトークンを生成できます。また、このドキュメントでは、APIクライアントの使用中に発生する一般的な問題のトラブルシューティングについても説明します。

設定

APIクライアントの作成

1. コントローラUIにアカウント所有者ロールまたはAdministration、Agents、Getting Startedウィザード権限を持つロールとしてログインします。
2. User Name（右上） > Administrationの順にクリックします。
3. API Client Tabをクリックします。
4. +作成をクリックします。
5. Client NameとDescriptionを入力します。
6. Generate Secretをクリックして、Client Secretを入力します。
   
   

   注：クライアントシークレットが生成され、表示されるのは1回だけです。この情報をコピーして安全に保存します。

7. Default Token Expirationを設定します。

8. ロールを追加するには、ロールセクションで+追加をクリックします。 
9. 右上のSaveをクリックします。

既存のAPIクライアントの表示

1. コントローラUIにアカウント所有者ロールまたはAdministration、Agents、Getting Startedウィザード権限を持つロールとしてログインします。
2. User Name（右上隅） > Administrationの順にクリックします。
3. API Clientタブをクリックして、既存のAPI Clientを表示します。

既存のAPIクライアントの削除

1. コントローラUIにアカウント所有者ロールまたはAdministration、Agents、Getting Startedウィザード権限を持つロールとしてログインします。
2. ユーザ名（右上隅）> 管理> APIクライアントをクリックします。
3. 削除する特定のAPIクライアントを検索して選択します。
4. 既存のAPIクライアントを削除するには、選択したAPIクライアントで削除アイコンをクリックするか右クリックして、APIクライアントの削除を選択します。

警告: APIクライアントを削除すると、トークンが無効になります。

アクセストークンの生成

アクセストークンは、管理者UIまたはOAuth APIを使用して生成できます。UIは長時間のトークンを提供し、OAuth APIは短時間の定期的な更新トークンを生成します。

• 管理者UI （長期間にわたって使用されるトークン）

  • コントローラUIにアカウント所有者ロールまたはAdministration、Agents、Getting Startedウィザード権限を持つロールとしてログインします。
  • ユーザ名（右上隅）> 管理> APIクライアントをクリックします。
  • アクセストークンを生成するAPIクライアントを選択し、Generate Temporary Access Tokenをクリックします。
  • UIから生成されたアクセストークンの有効期限が長くなっています。
    
    

• OAuth API （短期トークン）

  • REST APIを使用すると、短期間のアクセストークンを生成できます。 
    
    

    curl -X POST -H "Content-Type: application/x-www-form-urlencoded" "https:///controller/api/oauth/access_token" -d 'grant_type=client_credentials&client_id=@&client_secret='

    
    置換：
    

    •  APIクライアントの作成時に入力したクライアント名、または管理者が共有するクライアント名を使用します。

    • アカウント名を使用します。 

    • APIクライアントの作成時に生成したクライアントシークレット、または管理者によって共有されたクライアントシークレットを使用します。
      

      

      注:オンデマンドトークンはUIでは追跡されません。

      回答例：
      

      {
      "access_token": "",
      "expires_in": 300
      }​

アクセストークンの管理

• REST APIから生成されたアクセストークンを無効にするには、関連付けられているAPIクライアントを削除する必要があります。
• コントローラUIで生成されたアクセストークンは、取り消しまたは再生成できます。
• アクセストークンを再生成しても、以前のトークンは無効になりません。古いトークンは、有効期限が切れるまでアクティブなままです。
• 以前または現在有効なトークンを取得する方法はありません。したがって、失効できるのは現在のトークンだけです。
  
  

  • アクセストークンの再生成

    • コントローラUIにアカウント所有者ロールまたはAdministration、Agents、Getting Startedウィザード権限を持つロールとしてログインします。
    • ユーザ名（右上隅）> 管理> APIクライアントをクリックします。
    • アクセストークンを再生成するAPIクライアントを選択し、Regenerate > Save（右上隅）をクリックします。

  • アクセストークンの取り消し

    • コントローラUIにアカウント所有者ロールまたはAdministration、Agents、Getting Startedウィザード権限を持つロールとしてログインします。
    • ユーザ名（右上隅）> Administration > API Clientsの順にクリックします。
    • アクセストークンを失効させるAPI Clientを選択し、Revoke > Save（右上隅）をクリックします。

アクセストークンを使用してRest APIを作成する

• Splunk AppDynamics APIからd対話する必要がある特定のエンドポイントを決定します。 
  
• 要求を構成します。
  • Method：実行するアクションに基づいてHTTPメソッド(GET、POST、PUT、DELETE)を選択します。
  • ヘッダー：承認ヘッダーにアクセストークンを追加します。
  • 本文（存在する場合）: JavaScript Object Notation (JSON)形式でリクエスト本文を追加します。 
    
    
• 要求の例
  

  curl --location --request GET 'https:///controller/' --header 'Authorization: Bearer '

  
  置換：
  
  •   コントローラのURLを使用します。
  •   restエンドポイントと対話する必要があります。
  •   クライアント名とクライアントシークレットを使用して生成されたアクセストークンを使用します。

一般的な問題と解決策

• 401 Unauthorized
  

  • 問題：アクセストークンを生成しようとすると、401 Unauthorizedエラーが発生します。
  • サンプル応答： 
    

    
    
    
    HTTP Error 401 Unauthorized
    
    This request requires HTTP authentication
    

  • 根本原因：この問題は通常、クライアント名に関連付けられたクライアントシークレットが無効であるために発生します。これは、クライアントシークレットが生成されたが保存されていない場合によく発生します
  • ソリューション： 
    • コントローラUIにアカウント所有者ロールまたはAdministration、Agents、Getting Startedウィザード権限を持つロールとしてログインします。
    • User Name（右上隅） > Administrationの順にクリックします。
    • API Client Tabをクリックして、既存のAPIクライアントを表示します。
    • エラーを受け取るAPIクライアントを選択します。
    • Generate Secretをクリックして新しいクライアントシークレットを生成し、Save（右上隅）をクリックします 
      
      
      

• 空の応答です。

  • 問題：アクセストークンの生成に成功した後でも、RESTエンドポイントを照会すると空の応答が発生します。
  • サンプル応答：
    

  • 根本的な原因：この問題は通常、APIクライアントに割り当てられているロールまたは権限が不十分なために発生します。必要なロールがないと、APIクライアントはエンドポイントから必要なデータを取得できません。
  • ソリューション： 
    • コントローラUIにアカウント所有者ロールまたはAdministration、Agents、Getting Startedウィザード権限を持つロールとしてログインします。
    • User Name（右上隅） > Administrationの順にクリックします。
    • API Client Tabをクリックして、既存のAPIクライアントを表示します。
    • ロールを割り当てるAPIクライアントを選択します
    • ロールを追加するには、ロールセクションで+追加をクリックします。 
    • 右上のSaveをクリックします。
      
      
      

      注:APIクライアントに適切なロールが割り当てられていることを確認します。ロールは、RESTエンドポイントのデータアクセス要件に合わせる必要があります。

• 無効なコンテンツタイプ

  • 問題：アクセストークンの生成中に500内部サーバーエラーが発生しました。
  • サンプルエラー： 
    

    HTTP ERROR 500 javax.servlet.ServletException: java.lang.IllegalStateException: The @FormParam is utilized when the content type of the request entity is not application/x-www-form-urlencoded
    ​

  • 根本原因：問題はコンテンツタイプのヘッダーが原因で発生します。コントローラバージョン24.10では、コンテンツタイプがapplication/vnd.appd.cntrl+json;v=1からapplication/x-www-form-urlencodedに変更されました
  • ソリューション： 
    • 要求を変更し、コンテンツタイプヘッダーをapplication/x-www-form-urlencodedに設定します。
      例：
      

      curl -X POST -H "Content-Type: application/x-www-form-urlencoded" "https:///controller/api/oauth/access_token" -d 'grant_type=client_credentials&client_id=@&client_secret='​

関連情報

AppDynamicsドキュメント

Splunk AppDynamics API

API クライアント

アクセストークンの管理

サポートが必要な場合

質問がある場合、または問題が発生した場合は、次の詳細情報を記載したサポートチケットを作成してください。

• エラーの詳細またはスクリーンショット：特定のエラーメッセージまたは問題のスクリーンショットを提供します。
• 使用するコマンド：問題が発生したときに実行していたコマンドを正確に指定します。
• コントローラServer.log（オンプレミスのみ）:該当する場合、<controller-install-dir>/logs/server.log* からコントローラサーバログを提供します。