ラベルを使用してリソースを整理する

このページでは、Transcoder API リソースのラベルを追加および表示する方法について説明します。ラベルは、リソースの整理に使用できる Key-Value ペアです。 個々のリソースにラベルを設定し、そのラベルに基づいてリソースをフィルタリングできます。ラベルに関する情報は課金システムに転送されるため、ラベルを基準に請求料金を分析することもできます。

Transcoder API のジョブとジョブ テンプレートを作成するときに、ラベルを追加できます。ラベルを含むジョブ テンプレートに基づいてジョブを作成する場合、ジョブにはジョブ テンプレートと同じラベルが含まれます。ジョブ テンプレートのラベルをオーバーライドするには、ジョブ自体のラベルを直接指定します。

注: 既存の Transcoder API のリソースは不変であるため、これらのリソースではラベルを追加、編集、削除できません。

ラベルは REST API または RPC API によって使用できます。ラベルは Google Cloud CLI や Google Cloud コンソールでは使用できません。

ラベルの要件

リソースに適用するラベルは、次の要件を満たす必要があります。

• 1 つのリソースには、最大 64 個のラベルを適用できます。
• ラベルは、Key-Value ペアでなければなりません。
• キーは 1 文字以上、63 文字までにする必要があります。空にすることはできません。値は 63 文字以下にします。空にすることもできます。
• キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。
• ラベルのキーは単一のリソース内で一意であることが必要ですが、同じキーを複数のリソースで使用できます。
• キーは、小文字または国際文字で始める必要があります。

ジョブへのラベルの追加

次のサンプルは、新しいジョブを作成するときにラベルを追加する方法を示しています。 たとえば、ジョブをテスト環境で使用することを示すために、ラベルを使用できます。ラベルのキーは environment で、値は test です。

ジョブを作成するには、projects.locations.jobs.create メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

• PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
• LOCATION: ジョブを実行するロケーション。サポートされているリージョンのいずれかを使用します。
  • us-central1
  • us-west1
  • us-west2
  • us-east1
  • us-east4
  • southamerica-east1
  • asia-east1
  • asia-south1
  • asia-southeast1
  • europe-west1
  • europe-west2
  • europe-west4
• STORAGE_BUCKET_NAME: 作成した Cloud Storage バケットの名前。
• STORAGE_INPUT_VIDEO: コード変換する Cloud Storage バケット内の動画の名前（my-vid.mp4 など）。このフィールドでは、バケットで作成したフォルダ（input/my-vid.mp4 など）を考慮する必要があります。
  注: preset/web-hd プリセットを使用するには、入力動画に動画トラックと音声トラックが少なくとも 1 つずつ必要です。
• STORAGE_OUTPUT_FOLDER: エンコードされた動画出力を保存する Cloud Storage フォルダ名。
  注: ジョブを作成する前に出力フォルダ オブジェクトを作成する必要はありません。ジョブを処理する際、Transcoder API は、自動的に指定したフォルダ名を Cloud Storage に保存されたオブジェクトの名前の一部として先頭に付加します。

JSON 本文のリクエスト

{
  "inputUri": "gs://STORAGE_BUCKET_NAME/STORAGE_INPUT_VIDEO",
  "outputUri": "gs://STORAGE_BUCKET_NAME/STORAGE_OUTPUT_FOLDER/",
  "templateId": "preset/web-hd",
  "labels": {
    "environment": "test"
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 以下のコマンドでは、ご利用のユーザー アカウントで gcloud を認証する際に gcloud init または gcloud auth login を使用していることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存します。 ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

cat > request.json << 'EOF'
{
  "inputUri": "gs://STORAGE_BUCKET_NAME/STORAGE_INPUT_VIDEO",
  "outputUri": "gs://STORAGE_BUCKET_NAME/STORAGE_OUTPUT_FOLDER/",
  "templateId": "preset/web-hd",
  "labels": {
    "environment": "test"
  }
}
EOF

そのうえで、次のコマンドを実行して REST リクエストを送信します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://transcoder.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs"

PowerShell（Windows）

注: 以下のコマンドでは、ご利用のユーザー アカウントで gcloud を認証する際に gcloud init または gcloud auth login を使用していることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存します。 ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

@'
{
  "inputUri": "gs://STORAGE_BUCKET_NAME/STORAGE_INPUT_VIDEO",
  "outputUri": "gs://STORAGE_BUCKET_NAME/STORAGE_OUTPUT_FOLDER/",
  "templateId": "preset/web-hd",
  "labels": {
    "environment": "test"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

そのうえで、次のコマンドを実行して REST リクエストを送信します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://transcoder.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/jobs/JOB_ID",
  "config": {
    "inputs": [
      {
        "key": "input0",
        "uri": "gs://STORAGE_BUCKET_NAME/STORAGE_INPUT_VIDEO"
      }
    ],
    "editList": [
      {
        "key": "atom0",
        "inputs": [
          "input0"
        ],
        "startTimeOffset": "0s"
      }
    ],
    "elementaryStreams": [
      {
        "videoStream": {
          "h264": {
            "widthPixels": 640,
            "heightPixels": 360,
            "frameRate": 30,
            "bitrateBps": 550000,
            "pixelFormat": "yuv420p",
            "rateControlMode": "vbr",
            "crfLevel": 21,
            "gopDuration": "3s",
            "vbvSizeBits": 550000,
            "vbvFullnessBits": 495000,
            "entropyCoder": "cabac",
            "bFrameCount": 3,
            "aqStrength": 1,
            "profile": "high",
            "preset": "veryfast"
          }
        },
        "key": "video-stream0"
      },
      {
        "videoStream": {
          "h264": {
            "widthPixels": 1280,
            "heightPixels": 720,
            "frameRate": 30,
            "bitrateBps": 2500000,
            "pixelFormat": "yuv420p",
            "rateControlMode": "vbr",
            "crfLevel": 21,
            "gopDuration": "3s",
            "vbvSizeBits": 2500000,
            "vbvFullnessBits": 2250000,
            "entropyCoder": "cabac",
            "bFrameCount": 3,
            "aqStrength": 1,
            "profile": "high",
            "preset": "veryfast"
          }
        },
        "key": "video-stream1"
      },
      {
        "audioStream": {
          "codec": "aac",
          "bitrateBps": 64000,
          "channelCount": 2,
          "channelLayout": [
            "fl",
            "fr"
          ],
          "sampleRateHertz": 48000
        },
        "key": "audio-stream0"
      }
    ],
    "muxStreams": [
      {
        "key": "sd",
        "fileName": "sd.mp4",
        "container": "mp4",
        "elementaryStreams": [
          "video-stream0",
          "audio-stream0"
        ]
      },
      {
        "key": "hd",
        "fileName": "hd.mp4",
        "container": "mp4",
        "elementaryStreams": [
          "video-stream1",
          "audio-stream0"
        ]
      },
      {
        "key": "media-sd",
        "fileName": "media-sd.ts",
        "container": "ts",
        "elementaryStreams": [
          "video-stream0",
          "audio-stream0"
        ]
      },
      {
        "key": "media-hd",
        "fileName": "media-hd.ts",
        "container": "ts",
        "elementaryStreams": [
          "video-stream1",
          "audio-stream0"
        ]
      },
      {
        "key": "video-only-sd",
        "fileName": "video-only-sd.m4s",
        "container": "fmp4",
        "elementaryStreams": [
          "video-stream0"
        ]
      },
      {
        "key": "video-only-hd",
        "fileName": "video-only-hd.m4s",
        "container": "fmp4",
        "elementaryStreams": [
          "video-stream1"
        ]
      },
      {
        "key": "audio-only",
        "fileName": "audio-only.m4s",
        "container": "fmp4",
        "elementaryStreams": [
          "audio-stream0"
        ]
      }
    ],
    "manifests": [
      {
        "fileName": "manifest.m3u8",
        "type": "HLS",
        "muxStreams": [
          "media-sd",
          "media-hd"
        ]
      },
      {
        "fileName": "manifest.mpd",
        "type": "DASH",
        "muxStreams": [
          "video-only-sd",
          "video-only-hd",
          "audio-only"
        ]
      }
    ],
    "output": {
      "uri": "gs://STORAGE_BUCKET_NAME/STORAGE_OUTPUT_FOLDER/"
    }
  },
  "state": "PENDING",
  "createTime": CREATE_TIME,
  "ttlAfterCompletionDays": 30,
  "labels": {
    "environment": "test"
  }
}

複数のラベルを追加するには、各ラベルをカンマで区切ります。

ラベルによる一覧表示とフィルタリング

リソースを一覧表示し、そのラベルでフィルタリングできます。たとえば、ジョブにラベルを追加すると、特定のロケーションのジョブを一覧表示し、追加したラベルでフィルタリングできます。次のサンプルでは、ジョブを一覧表示し、ラベル "environment": "test" を含まないジョブを除外しています。

ジョブを一覧表示するには、projects.locations.jobs.list メソッドを使用します。次のフィルタが URL に追加されます: ?filter=labels.environment:test。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: Google Cloud プロジェクト ID

LOCATION: ジョブのロケーション。サポートされているリージョンのいずれかを使用します。

• us-central1
• us-west1
• us-west2
• us-east1
• us-east4
• southamerica-east1
• asia-east1
• asia-south1
• asia-southeast1
• europe-west1
• europe-west2
• europe-west4

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 以下のコマンドでは、ご利用のユーザー アカウントで gcloud を認証する際に gcloud init または gcloud auth login を使用していることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth print-access-token) \
"https://transcoder.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs?filter=labels.environment:test"

PowerShell（Windows）

注: 以下のコマンドでは、ご利用のユーザー アカウントで gcloud を認証する際に gcloud init または gcloud auth login を使用していることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://transcoder.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs?filter=labels.environment:test" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "jobs": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/jobs/MY_JOB",
      "config": {
        ....
       },
      "state": "PENDING",
      "createTime": CREATE_TIME,
      "ttlAfterCompletionDays": 30,
      "labels": {
        "environment": "test"
      }
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/jobs/MY_OTHER_JOB",
      "config": {
        ....
       },
      "state": "SUCCEEDED",
      "createTime": CREATE_TIME,
      "startTime": START_TIME,
      "endTime": END_TIME,
      "ttlAfterCompletionDays": 30,
      "labels": {
        "environment": "test"
      }
    }
  ]
}