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

このページでは、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
  • northamerica-northeast1
  • asia-east1
  • asia-northeast1
  • asia-northeast3
  • asia-south1
  • asia-southeast1
  • australia-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 に保存されたオブジェクトの名前の一部として先頭に付加します。

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。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 init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。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
• northamerica-northeast1
• asia-east1
• asia-northeast1
• asia-northeast3
• asia-south1
• asia-southeast1
• australia-southeast1
• europe-west1
• europe-west2
• europe-west4

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。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 init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。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"
      }
    }
  ]
}