Hadoop YARN - Webサービス REST API の概要

概要
URI
HTTPリクエスト
HTTPレスポンス
サンプル使用

概要

Hadoop YARN Webサービス REST APIは、クラスター、ノード、アプリケーション、およびアプリケーションの履歴情報へのアクセスを提供するURIリソースのセットです。URIリソースは、返される情報の種類に基づいてAPIにグループ化されます。一部のURIリソースはコレクションを返し、他のリソースはシングルトンを返します。

URI

RESTベースのWebサービスのURIは、次の構文を持ちます。

  http://{http address of service}/ws/{version}/{resourcepath}

この構文の要素は次のとおりです。

  {http address of service} - The http address of the service to get information about. 
                              Currently supported are the ResourceManager, NodeManager, 
                              MapReduce application master, and history server.
  {version} - The version of the APIs. In this release, the version is v1.
  {resourcepath} - A path that defines a singleton resource or a collection of resources.

HTTPリクエスト

REST APIを呼び出すには、アプリケーションはリソースに関連付けられたURIに対してHTTP操作を呼び出します。

HTTP操作の概要

現在、GETのみがサポートされています。指定されたリソースに関する情報を取得します。

セキュリティ

WebサービスREST APIは、Web UIと同じセキュリティを使用します。クラスター管理者がフィルターを有効にしている場合は、指定されたメカニズムを介して認証する必要があります。

サポートされるヘッダー

Accept
- Accept-Encoding

現在、ヘッダーで使用されるフィールドはAcceptとAccept-Encodingのみです。Acceptは現在、応答タイプとしてXMLとJSONをサポートしています。Accept-Encodingは現在gzip形式のみをサポートしており、これが指定されている場合はgzip圧縮された出力が返され、それ以外の場合は圧縮されていない出力が返されます。他のすべてのヘッダーフィールドは無視されます。

HTTPレスポンス

次のいくつかのセクションでは、WebサービスREST APIのHTTPレスポンスの構文とその他の詳細について説明します。

圧縮

このリリースでは、HTTPリクエストのAccept-Encodingヘッダーにgzipを指定した場合（Accept-Encoding：gzip）gzip圧縮がサポートされています。

レスポンス形式

このリリースのWebサービスREST APIは、JSONおよびXML形式でのレスポンスをサポートしています。JSONがデフォルトです。レスポンス形式を設定するには、HTTPリクエストのAcceptヘッダーで形式を指定できます。

HTTPレスポンスコードで指定されているように、レスポンスボディには、リソースを表すデータまたはエラーメッセージを含めることができます。成功の場合、レスポンスボディは、選択した形式（JSONまたはXML）になります。エラーの場合、レスポンスボディは、リクエストされた形式に基づいてJSONまたはXMLのいずれかになります。レスポンスのContent-Typeヘッダーには、リクエストされた形式が含まれます。アプリケーションがサポートされていない形式をリクエストした場合、レスポンスステータスコードは500になります。レスポンスボディ内のフィールドの順序は指定されておらず、変更される可能性があることに注意してください。また、レスポンスボディにフィールドが追加される場合もあります。したがって、アプリケーションは、任意の順序でレスポンスボディからデータを抽出できる解析ルーチンを使用する必要があります。

レスポンスエラー

HTTPリクエストを呼び出した後、アプリケーションはレスポンスステータスコードをチェックして、成功を確認するか、エラーを検出する必要があります。レスポンスステータスコードがエラーを示している場合、レスポンスボディにはエラーメッセージが含まれます。最初のフィールドは例外タイプであり、現在RemoteExceptionのみが返されます。次の表に、RemoteExceptionエラーメッセージ内の項目を示します。

項目	データ型	説明
exception	文字列	例外タイプ
javaClassName	文字列	例外のJavaクラス名
message	文字列	例外の詳細メッセージ

レスポンス例

単一リソースでのJSONレスポンス

_1324057493980_0001HTTPリクエスト: GET http://rmhost.domain:8088/ws/v1/cluster/apps/application

レスポンスステータス行: HTTP/1.1 200 OK

レスポンスヘッダー

  HTTP/1.1 200 OK
  Content-Type: application/json
  Transfer-Encoding: chunked
  Server: Jetty(6.1.26)

レスポンスボディ

{
  app":
  {
    "id":"application_1324057493980_0001",
    "user":"user1",
    "name":"",
    "queue":"default",
    "state":"ACCEPTED",
    "finalStatus":"UNDEFINED",
    "progress":0,
    "trackingUI":"UNASSIGNED",
    "diagnostics":"",
    "clusterId":1324057493980,
    "startedTime":1324057495921,
    "finishedTime":0,
    "elapsedTime":2063,
    "amContainerLogs":"http:\/\/amNM:2\/node\/containerlogs\/container_1324057493980_0001_01_000001",
    "amHostHttpAddress":"amNM:2"
  }
}

エラーレスポンスでのJSONレスポンス

ここでは、まだ存在しないアプリケーションに関する情報をリクエストします。

_1324057493980_9999HTTPリクエスト: GET http://rmhost.domain:8088/ws/v1/cluster/apps/application

レスポンスステータス行: HTTP/1.1 404 Not Found

レスポンスヘッダー

  HTTP/1.1 404 Not Found
  Content-Type: application/json
  Transfer-Encoding: chunked
  Server: Jetty(6.1.26)

レスポンスボディ

{
   "RemoteException" : {
      "javaClassName" : "org.apache.hadoop.yarn.webapp.NotFoundException",
      "exception" : "NotFoundException",
      "message" : "java.lang.Exception: app with id: application_1324057493980_9999 not found"
   }
}

サンプル使用

WebサービスREST APIを使用するには、さまざまな方法/言語を使用できます。この例では、curlコマンドラインインターフェースを使用してREST GET呼び出しを行います。

この例では、ユーザーは次のようなコマンドを使用して、MapReduceアプリケーションをResourceManagerに送信します。

  hadoop jar hadoop-mapreduce-test.jar sleep -Dmapred.job.queue.name=a1 -m 1 -r 1 -rt 1200000 -mt 20

クライアントは、次のようなアプリケーションIDとともに、送信されたジョブに関する情報を出力します。

12/01/18 04:25:15 INFO mapred.ResourceMgrDelegate: Submitted application application_1326821518301_0010 to ResourceManager at host.domain.com/10.10.10.10:8032
12/01/18 04:25:15 INFO mapreduce.Job: Running job: job_1326821518301_0010
12/01/18 04:25:21 INFO mapred.ClientServiceDelegate: The url to track the job: host.domain.com:8088/proxy/application_1326821518301_0010/
12/01/18 04:25:22 INFO mapreduce.Job: Job job_1326821518301_0010 running in uber mode : false
12/01/18 04:25:22 INFO mapreduce.Job:  map 0% reduce 0%

次に、ユーザーはアプリケーションを追跡したいと考えています。ユーザーは、まずResourceManagerからアプリケーションに関する情報を取得します。出力圧縮をリクエストするには、–compressedオプションを使用します。curlはクライアント側での解凍を処理します。

curl --compressed -H "Accept: application/json" -X GET "http://host.domain.com:8088/ws/v1/cluster/apps/application_1326821518301_0010"

出力

{
   "app" : {
      "finishedTime" : 0,
      "amContainerLogs" : "http://host.domain.com:8042/node/containerlogs/container_1326821518301_0010_01_000001",
      "trackingUI" : "ApplicationMaster",
      "state" : "RUNNING",
      "user" : "user1",
      "id" : "application_1326821518301_0010",
      "clusterId" : 1326821518301,
      "finalStatus" : "UNDEFINED",
      "amHostHttpAddress" : "host.domain.com:8042",
      "progress" : 82.44703,
      "name" : "Sleep job",
      "startedTime" : 1326860715335,
      "elapsedTime" : 31814,
      "diagnostics" : "",
      "trackingUrl" : "http://host.domain.com:8088/proxy/application_1326821518301_0010/",
      "queue" : "a1"
   }
}

_1326821518301_0010。これはWebブラウザーに送られるか、WebサービスREST APIを使用できます。次に、ユーザーは実行中のアプリケーションに関する詳細情報を取得し、このアプリケーションのMapReduceアプリケーションマスターに直接移動します。ResourceManagerは、このアプリケーションに使用できるtrackingUrlをリストします：http://host.domain.com:8088/proxy/application’s。ユーザーは、WebサービスREST APIを使用して、このMapReduceアプリケーションマスターが実行しているジョブのリストを取得します。

 curl --compressed -H "Accept: application/json" -X GET "http://host.domain.com:8088/proxy/application_1326821518301_0010/ws/v1/mapreduce/jobs"

出力

{
   "jobs" : {
      "job" : [
         {
            "runningReduceAttempts" : 1,
            "reduceProgress" : 72.104515,
            "failedReduceAttempts" : 0,
            "newMapAttempts" : 0,
            "mapsRunning" : 0,
            "state" : "RUNNING",
            "successfulReduceAttempts" : 0,
            "reducesRunning" : 1,
            "acls" : [
               {
                  "value" : " ",
                  "name" : "mapreduce.job.acl-modify-job"
               },
               {
                  "value" : " ",
                  "name" : "mapreduce.job.acl-view-job"
               }
            ],
            "reducesPending" : 0,
            "user" : "user1",
            "reducesTotal" : 1,
            "mapsCompleted" : 1,
            "startTime" : 1326860720902,
            "id" : "job_1326821518301_10_10",
            "successfulMapAttempts" : 1,
            "runningMapAttempts" : 0,
            "newReduceAttempts" : 0,
            "name" : "Sleep job",
            "mapsPending" : 0,
            "elapsedTime" : 64432,
            "reducesCompleted" : 0,
            "mapProgress" : 100,
            "diagnostics" : "",
            "failedMapAttempts" : 0,
            "killedReduceAttempts" : 0,
            "mapsTotal" : 1,
            "uberized" : false,
            "killedMapAttempts" : 0,
            "finishTime" : 0
         }
      ]
   }
}

次に、ユーザーは上記にリストされたジョブID job_1326821518301_10_10を持つジョブに関するタスクの詳細を取得したいと考えています。

 curl --compressed -H "Accept: application/json" -X GET "http://host.domain.com:8088/proxy/application_1326821518301_0010/ws/v1/mapreduce/jobs/job_1326821518301_10_10/tasks"

出力

{
   "tasks" : {
      "task" : [
         {
            "progress" : 100,
            "elapsedTime" : 5059,
            "state" : "SUCCEEDED",
            "startTime" : 1326860725014,
            "id" : "task_1326821518301_10_10_m_0",
            "type" : "MAP",
            "successfulAttempt" : "attempt_1326821518301_10_10_m_0_0",
            "finishTime" : 1326860730073
         },
         {
            "progress" : 72.104515,
            "elapsedTime" : 0,
            "state" : "RUNNING",
            "startTime" : 1326860732984,
            "id" : "task_1326821518301_10_10_r_0",
            "type" : "REDUCE",
            "successfulAttempt" : "",
            "finishTime" : 0
         }
      ]
   }
}

マップタスクは終了しましたが、リデュースタスクはまだ実行中です。ユーザーはリデュースタスクtask_1326821518301_10_10_r_0のタスク試行情報を取得したいと考えています。JSONがデフォルトの出力形式であるため、Acceptヘッダーはここでは必須ではないことに注意してください。

  curl --compressed -X GET "http://host.domain.com:8088/proxy/application_1326821518301_0010/ws/v1/mapreduce/jobs/job_1326821518301_10_10/tasks/task_1326821518301_10_10_r_0/attempts"

出力

{
   "taskAttempts" : {
      "taskAttempt" : [
         {
            "elapsedMergeTime" : 158,
            "shuffleFinishTime" : 1326860735378,
            "assignedContainerId" : "container_1326821518301_0010_01_000003",
            "progress" : 72.104515,
            "elapsedTime" : 0,
            "state" : "RUNNING",
            "elapsedShuffleTime" : 2394,
            "mergeFinishTime" : 1326860735536,
            "rack" : "/10.10.10.0",
            "elapsedReduceTime" : 0,
            "nodeHttpAddress" : "host.domain.com:8042",
            "type" : "REDUCE",
            "startTime" : 1326860732984,
            "id" : "attempt_1326821518301_10_10_r_0_0",
            "finishTime" : 0
         }
      ]
   }
}

リデュース試行はまだ実行中で、ユーザーはその試行の現在のカウンター値を表示したいと考えています。

 curl --compressed -H "Accept: application/json"  -X GET "http://host.domain.com:8088/proxy/application_1326821518301_0010/ws/v1/mapreduce/jobs/job_1326821518301_10_10/tasks/task_1326821518301_10_10_r_0/attempts/attempt_1326821518301_10_10_r_0_0/counters"

出力

{
   "JobTaskAttemptCounters" : {
      "taskAttemptCounterGroup" : [
         {
            "counterGroupName" : "org.apache.hadoop.mapreduce.FileSystemCounter",
            "counter" : [
               {
                  "value" : 4216,
                  "name" : "FILE_BYTES_READ"
               }, 
               {
                  "value" : 77151,
                  "name" : "FILE_BYTES_WRITTEN"
               }, 
               {
                  "value" : 0,
                  "name" : "FILE_READ_OPS"
               },
               {
                  "value" : 0,
                  "name" : "FILE_LARGE_READ_OPS"
               },
               {
                  "value" : 0,
                  "name" : "FILE_WRITE_OPS"
               },
               {
                  "value" : 0,
                  "name" : "HDFS_BYTES_READ"
               },
               {
                  "value" : 0,
                  "name" : "HDFS_BYTES_WRITTEN"
               },
               {
                  "value" : 0,
                  "name" : "HDFS_READ_OPS"
               },
               {
                  "value" : 0,
                  "name" : "HDFS_LARGE_READ_OPS"
               },
               {
                  "value" : 0,
                  "name" : "HDFS_WRITE_OPS"
               }
            ]  
         }, 
         {
            "counterGroupName" : "org.apache.hadoop.mapreduce.TaskCounter",
            "counter" : [
               {
                  "value" : 0,
                  "name" : "COMBINE_INPUT_RECORDS"
               }, 
               {
                  "value" : 0,
                  "name" : "COMBINE_OUTPUT_RECORDS"
               }, 
               {  
                  "value" : 1767,
                  "name" : "REDUCE_INPUT_GROUPS"
               },
               {  
                  "value" : 25104,
                  "name" : "REDUCE_SHUFFLE_BYTES"
               },
               {
                  "value" : 1767,
                  "name" : "REDUCE_INPUT_RECORDS"
               },
               {
                  "value" : 0,
                  "name" : "REDUCE_OUTPUT_RECORDS"
               },
               {
                  "value" : 0,
                  "name" : "SPILLED_RECORDS"
               },
               {
                  "value" : 1,
                  "name" : "SHUFFLED_MAPS"
               },
               {
                  "value" : 0,
                  "name" : "FAILED_SHUFFLE"
               },
               {
                  "value" : 1,
                  "name" : "MERGED_MAP_OUTPUTS"
               },
               {
                  "value" : 50,
                  "name" : "GC_TIME_MILLIS"
               },
               {
                  "value" : 1580,
                  "name" : "CPU_MILLISECONDS"
               },
               {
                  "value" : 141320192,
                  "name" : "PHYSICAL_MEMORY_BYTES"
               },
              {
                  "value" : 1118552064,
                  "name" : "VIRTUAL_MEMORY_BYTES"
               }, 
               {  
                  "value" : 73728000,
                  "name" : "COMMITTED_HEAP_BYTES"
               }
            ]
         },
         {  
            "counterGroupName" : "Shuffle Errors",
            "counter" : [
               {  
                  "value" : 0,
                  "name" : "BAD_ID"
               },
               {  
                  "value" : 0,
                  "name" : "CONNECTION"
               },
               {  
                  "value" : 0,
                  "name" : "IO_ERROR"
               },
               {  
                  "value" : 0,
                  "name" : "WRONG_LENGTH"
               },
               {  
                  "value" : 0,
                  "name" : "WRONG_MAP"
               },
               {  
                  "value" : 0,
                  "name" : "WRONG_REDUCE"
               }
            ]
         },
         {  
            "counterGroupName" : "org.apache.hadoop.mapreduce.lib.output.FileOutputFormatCounter",
            "counter" : [
              {  
                  "value" : 0,
                  "name" : "BYTES_WRITTEN"
               }
            ]
         }
      ],
      "id" : "attempt_1326821518301_10_10_r_0_0"
   }
}

ジョブが終了し、ユーザーはこのジョブの履歴サーバーから最終的なジョブ情報を取得したいと考えています。

  curl --compressed -X GET "http://host.domain.com:19888/ws/v1/history/mapreduce/jobs/job_1326821518301_10_10"

出力

{
   "job" : {
      "avgReduceTime" : 1250784,
      "failedReduceAttempts" : 0,
      "state" : "SUCCEEDED",
      "successfulReduceAttempts" : 1,
      "acls" : [
         {
            "value" : " ",
            "name" : "mapreduce.job.acl-modify-job"
         },
         {
            "value" : " ",
            "name" : "mapreduce.job.acl-view-job"
         }
      ],
      "user" : "user1",
      "reducesTotal" : 1,
      "mapsCompleted" : 1,
      "startTime" : 1326860720902,
      "id" : "job_1326821518301_10_10",
      "avgMapTime" : 5059,
      "successfulMapAttempts" : 1,
      "name" : "Sleep job",
      "avgShuffleTime" : 2394,
      "reducesCompleted" : 1,
      "diagnostics" : "",
      "failedMapAttempts" : 0,
      "avgMergeTime" : 2552,
      "killedReduceAttempts" : 0,
      "mapsTotal" : 1,
      "queue" : "a1",
      "uberized" : false,
      "killedMapAttempts" : 0,
      "finishTime" : 1326861986164
   }
}

ユーザーは、ResourceManagerから最終的なアプリケーション情報も取得します。

  curl --compressed -H "Accept: application/json" -X GET "http://host.domain.com:8088/ws/v1/cluster/apps/application_1326821518301_0010"

出力

{
   "app" : {
      "finishedTime" : 1326861991282,
      "amContainerLogs" : "http://host.domain.com:8042/node/containerlogs/container_1326821518301_0010_01_000001",
      "trackingUI" : "History",
      "state" : "FINISHED",
      "user" : "user1",
      "id" : "application_1326821518301_0010",
      "clusterId" : 1326821518301,
      "finalStatus" : "SUCCEEDED",
      "amHostHttpAddress" : "host.domain.com:8042",
      "progress" : 100,
      "name" : "Sleep job",
      "startedTime" : 1326860715335,
      "elapsedTime" : 1275947,
      "diagnostics" : "",
      "trackingUrl" : "http://host.domain.com:8088/proxy/application_1326821518301_0010/jobhistory/job/job_1326821518301_10_10",
      "queue" : "a1"
   }
}

一般

共通

HDFS

MapReduce

MapReduce REST API

YARN

YARN REST API

YARNサービス

Hadoop互換ファイルシステム

認証

ツール

リファレンス

構成