Creates a reporting job. By creating a reporting job, you are instructing YouTube to generate that report on a daily basis. The report is available within 24 hours of the time that the job is created.
Request
HTTP request
POST https://youtubereporting.googleapis.com/v1/jobs
Parameters
Query parameters
Parameters | |
---|---|
onBehalfOfContentOwner
|
string
The ID of the content owner for whom the API request is being made. If the request does not specify a value for this parameter, the API server assumes that the request is being made for the user's own channel. |
Request body
The request body contains a Job
resource that sets values for the reportTypeId
and name
properties.
Response
Success
The response body contains a Job resource.
Errors
-
Bad Request (400)
- The request did not specify a value for the
job
resource'sname
property. - The request did not specify a value for the
job
resource'sreportTypeId
property. - The
reportTypeId
specified in the request does not exist. - The request attempted to create a job for a deprecated report type.
- The request did not specify a value for the
-
Forbidden (403)
- The request attempted to create a job for a system-managed report . YouTube will automatically generate system-managed reports, and content owners will not be able to modify or delete jobs that create those reports.
-
Conflict (409)
- The request attempted to create a job that already exists.
Examples
Note:The code samples below may not represent all supported programming languages. See the client libraries documentation for a list of supported languages.
Java
The sample below uses the Java client library .
This sample demonstrates how to create a reporting job. It calls the reportTypes.list
method to retrieve a list of available report types. It then calls the jobs.create
method to create a new reporting job.
/* * Copyright (c) 2015 Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except * in compliance with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software distributed under the License * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express * or implied. See the License for the specific language governing permissions and limitations under * the License. */ package com.google.api.services.samples.youtube.cmdline.reporting ; import com.google.api.client.auth.oauth2.Credential ; import com.google.api.client.googleapis.json.GoogleJsonResponseException ; import com.google.api.services.samples.youtube.cmdline.Auth ; import com.google.api.services.youtubereporting.YouTubeReporting ; import com.google.api.services.youtubereporting.model.Job ; import com.google.api.services.youtubereporting.model.ListReportTypesResponse ; import com.google.api.services.youtubereporting.model.ReportType ; import com.google.common.collect.Lists ; import java.io.BufferedReader ; import java.io.IOException ; import java.io.InputStreamReader ; import java.util.List ; /** * This sample creates a reporting job by: * * 1. Listing the available report types using the "reportTypes.list" method. * 2. Creating a reporting job using the "jobs.create" method. * * @author Ibrahim Ulukaya */ public class CreateReportingJob { /** * Define a global instance of a YouTube Reporting object, which will be used to make * YouTube Reporting API requests. */ private static YouTubeReporting youtubeReporting ; /** * Create a reporting job. * * @param args command line args (not used). */ public static void main ( String [] args ) { /* * This OAuth 2.0 access scope allows for read access to the YouTube Analytics monetary reports for * authenticated user's account. Any request that retrieves earnings or ad performance metrics must * use this scope. */ List<String> scopes = Lists . newArrayList ( "https://www.googleapis.com/auth/yt-analytics-monetary.readonly" ); try { // Authorize the request. Credential credential = Auth . authorize ( scopes , "createreportingjob" ); // This object is used to make YouTube Reporting API requests. youtubeReporting = new YouTubeReporting . Builder ( Auth . HTTP_TRANSPORT , Auth . JSON_FACTORY , credential ) . setApplicationName ( "youtube-cmdline-createreportingjob-sample" ). build (); // Prompt the user to specify the name of the job to be created. String name = getNameFromUser (); if ( listReportTypes ()) { createReportingJob ( getReportTypeIdFromUser (), name ); } } catch ( GoogleJsonResponseException e ) { System . err . println ( "GoogleJsonResponseException code: " + e . getDetails (). getCode () + " : " + e . getDetails (). getMessage ()); e . printStackTrace (); } catch ( IOException e ) { System . err . println ( "IOException: " + e . getMessage ()); e . printStackTrace (); } catch ( Throwable t ) { System . err . println ( "Throwable: " + t . getMessage ()); t . printStackTrace (); } } /** * Lists report types. (reportTypes.listReportTypes) * @return true if at least one report type exists * @throws IOException */ private static boolean listReportTypes () throws IOException { // Call the YouTube Reporting API's reportTypes.list method to retrieve report types. ListReportTypesResponse reportTypesListResponse = youtubeReporting . reportTypes (). list () . execute (); List<ReportType> reportTypeList = reportTypesListResponse . getReportTypes (); if ( reportTypeList == null || reportTypeList . isEmpty ()) { System . out . println ( "No report types found." ); return false ; } else { // Print information from the API response. System . out . println ( "\n================== Report Types ==================\n" ); for ( ReportType reportType : reportTypeList ) { System . out . println ( " - Id: " + reportType . getId ()); System . out . println ( " - Name: " + reportType . getName ()); System . out . println ( "\n-------------------------------------------------------------\n" ); } } return true ; } /** * Creates a reporting job. (jobs.create) * * @param reportTypeId Id of the job's report type. * @param name name of the job. * @throws IOException */ private static void createReportingJob ( String reportTypeId , String name ) throws IOException { // Create a reporting job with a name and a report type id. Job job = new Job (); job . setReportTypeId ( reportTypeId ); job . setName ( name ); // Call the YouTube Reporting API's jobs.create method to create a job. Job createdJob = youtubeReporting . jobs (). create ( job ). execute (); // Print information from the API response. System . out . println ( "\n================== Created reporting job ==================\n" ); System . out . println ( " - ID: " + createdJob . getId ()); System . out . println ( " - Name: " + createdJob . getName ()); System . out . println ( " - Report Type Id: " + createdJob . getReportTypeId ()); System . out . println ( " - Create Time: " + createdJob . getCreateTime ()); System . out . println ( "\n-------------------------------------------------------------\n" ); } /* * Prompt the user to enter a name for the job. Then return the name. */ private static String getNameFromUser () throws IOException { String name = "" ; System . out . print ( "Please enter the name for the job [javaTestJob]: " ); BufferedReader bReader = new BufferedReader ( new InputStreamReader ( System . in )); name = bReader . readLine (); if ( name . length () < 1 ) { // If nothing is entered, defaults to "javaTestJob". name = "javaTestJob" ; } System . out . println ( "You chose " + name + " as the name for the job." ); return name ; } /* * Prompt the user to enter a report type id for the job. Then return the id. */ private static String getReportTypeIdFromUser () throws IOException { String id = "" ; System . out . print ( "Please enter the reportTypeId for the job: " ); BufferedReader bReader = new BufferedReader ( new InputStreamReader ( System . in )); id = bReader . readLine (); System . out . println ( "You chose " + id + " as the report type Id for the job." ); return id ; } }
PHP
The sample below uses the PHP client library .
This sample demonstrates how to create a reporting job. It calls the reportTypes.list
method to retrieve a list of available report types. It then calls the jobs.create
method to create a new reporting job.
< ?php /** * This sample creates a reporting job by: * * 1. Listing the available report types using the "reportTypes.list" method. * 2. Creating a reporting job using the "jobs.create" method. * * @author Ibrahim Ulukaya */ /** * Library Requirements * * 1. Install composer (https://getcomposer.org) * 2. On the command line, change to this directory (api-samples/php) * 3. Require the google/apiclient library * $ composer require google/apiclient:~2.0 */ if (!file_exists(__DIR__ . '/vendor/autoload.php')) { throw new \Exception('please run "composer require google/apiclient:~2.0" in "' . __DIR__ .'"'); } require_once __DIR__ . '/vendor/autoload.php'; session_start(); /* * You can acquire an OAuth 2.0 client ID and client secret from the * {{ Google Cloud Console }} <{{ https://cloud.google.com/console }} > * For more information about using OAuth 2.0 to access Google APIs, please see: * <https://developers.google.com/youtube/v3/guides/authentication> * Please ensure that you have enabled the YouTube Data API for your project. */ $OAUTH2_CLIENT_ID = 'REPLACE_ME'; $OAUTH2_CLIENT_SECRET = 'REPLACE_ME'; $client = new Google_Client(); $client->setClientId($OAUTH2_CLIENT_ID); $client->setClientSecret($OAUTH2_CLIENT_SECRET); /* * This OAuth 2.0 access scope allows for read access to the YouTube Analytics monetary reports for * authenticated user's account. Any request that retrieves earnings or ad performance metrics must * use this scope. */ $client->setScopes('https://www.googleapis.com/auth/yt-analytics-monetary.readonly'); $redirect = filter_var('http://' . $_SERVER['HTTP_HOST'] . $_SERVER['PHP_SELF'], FILTER_SANITIZE_URL); $client->setRedirectUri($redirect); // YouTube Reporting object used to make YouTube Reporting API requests. $youtubeReporting = new Google_Service_YouTubeReporting($client); // Check if an auth token exists for the required scopes $tokenSessionKey = 'token-' . $client->prepareScopes(); if (isset($_GET['code'])) { if (strval($_SESSION['state']) !== strval($_GET['state'])) { die('The session state did not match.'); } $client->authenticate($_GET['code']); $_SESSION[$tokenSessionKey] = $client->getAccessToken(); header('Location: ' . $redirect); } if (isset($_SESSION[$tokenSessionKey])) { $client->setAccessToken($_SESSION[$tokenSessionKey]); } // Check to ensure that the access token was successfully acquired. if ($client->getAccessToken()) { // This code executes if the user enters a name in the form // and submits the form. Otherwise, the page displays the form above. try { if (empty(listReportTypes($youtubeReporting, $htmlBody))) { $htmlBody .= sprintf('<p>No report types found.</p>'); } else if ($_GET['reportTypeId']){ createReportingJob($youtubeReporting, $_GET['reportTypeId'], $_GET['jobName'], $htmlBody); } } catch (Google_Service_Exception $e) { $htmlBody = sprintf('<p>A service error occurred: <code>%s</code></p>', htmlspecialchars($e->getMessage())); } catch (Google_Exception $e) { $htmlBody = sprintf('<p>An client error occurred: <code>%s</code></p>', htmlspecialchars($e->getMessage())); } $_SESSION[$tokenSessionKey] = $client->getAccessToken(); } elseif ($OAUTH2_CLIENT_ID == 'REPLACE_ME') { $htmlBody = <<<END <h3>Client Credentials Required</h3> <p> You need to set <code>\$OAUTH2_CLIENT_ID</code> and <code>\$OAUTH2_CLIENT_ID</code> before proceeding. <p> END; } else { // If the user hasn't authorized the app, initiate the OAuth flow $state = mt_rand(); $client->setState($state); $_SESSION['state'] = $state; $authUrl = $client->createAuthUrl(); $htmlBody = <<<END <h3>Authorization Required</h3> <p>You need to <a href="$authUrl">authorize access</a> before proceeding.<p> END; } /** * Creates a reporting job. (jobs.create) * * @param Google_Service_YouTubereporting $youtubeReporting YouTube Reporting service object. * @param string $reportTypeId Id of the job's report type. * @param string $name name of the job. * @param $htmlBody - html body. */ function createReportingJob(Google_Service_YouTubeReporting $youtubeReporting, $reportTypeId, $name, &$htmlBody) { # Create a reporting job with a name and a report type id. $reportingJob = new Google_Service_YouTubeReporting_Job(); $reportingJob->setReportTypeId($reportTypeId); $reportingJob->setName($name); // Call the YouTube Reporting API's jobs.create method to create a job. $jobCreateResponse = $youtubeReporting->jobs->create($reportingJob); $htmlBody .= "<h2>Created reporting job</h2><ul>"; $htmlBody .= sprintf('<li>"%s" for reporting type "%s" at "%s"</li>', $jobCreateResponse['name'], $jobCreateResponse['reportTypeId'], $jobCreateResponse['createTime']); $htmlBody .= '</ul>'; } /** * Returns a list of report types. (reportTypes.listReportTypes) * * @param Google_Service_YouTubereporting $youtubeReporting YouTube Reporting service object. * @param $htmlBody - html body. */ function listReportTypes(Google_Service_YouTubeReporting $youtubeReporting, &$htmlBody) { // Call the YouTube Reporting API's reportTypes.list method to retrieve report types. $reportTypes = $youtubeReporting->reportTypes->listReportTypes(); $htmlBody .= "<h3>Report Types</h3><ul>"; foreach ($reportTypes as $reportType) { $htmlBody .= sprintf('<li>id: "%s", name: "%s"</li>', $reportType['id'], $reportType['name']); } $htmlBody .= '</ul>'; return $reportTypes; } ? > < !doctype html > < html > < head > < title>Create a reporting job</title> < /head > < body > <form method="GET"> <div> Job Name: <input type="text" id="jobName" name="jobName" placeholder="Enter Job Name"> </div> <br> <div> Report Type Id: <input type="text" id="reportTypeId" name="reportTypeId" placeholder="Enter Report Type Id"> </div> <br> <input type="submit" value="Create!"> </form> <?=$htmlBody?> < /body > < /html >
Python
The sample below uses the Python client library .
This sample demonstrates how to create a reporting job. It calls the reportTypes.list
method to retrieve a list of available report types. It then calls the jobs.create
method to create a new reporting job.
#!/usr/bin/python # Create a reporting job for the authenticated user's channel or # for a content owner that the user's account is linked to. # Usage example: # python create_reporting_job.py --name='<name>' # python create_reporting_job.py --content-owner='<CONTENT OWNER ID>' # python create_reporting_job.py --content-owner='<CONTENT_OWNER_ID>' --report-type='<REPORT_TYPE_ID>' --name='<REPORT_NAME>' import argparse import os import google.oauth2.credentials import google_auth_oauthlib.flow from googleapiclient.discovery import build from googleapiclient.errors import HttpError from google_auth_oauthlib.flow import InstalledAppFlow # The CLIENT_SECRETS_FILE variable specifies the name of a file that contains # the OAuth 2.0 information for this application, including its client_id and # client_secret. You can acquire an OAuth 2.0 client ID and client secret from # the {{ Google Cloud Console }} at # {{ https://cloud.google.com/console }}. # Please ensure that you have enabled the YouTube Data API for your project. # For more information about using OAuth2 to access the YouTube Data API, see: # https://developers.google.com/youtube/v3/guides/authentication # For more information about the client_secrets.json file format, see: # https://developers.google.com/api-client-library/python/guide/aaa_client_secrets CLIENT_SECRETS_FILE = 'client_secret.json' # This OAuth 2.0 access scope allows for read access to the YouTube Analytics monetary reports for # authenticated user's account. Any request that retrieves earnings or ad performance metrics must # use this scope. SCOPES = [ 'https://www.googleapis.com/auth/yt-analytics-monetary.readonly' ] API_SERVICE_NAME = 'youtubereporting' API_VERSION = 'v1' # Authorize the request and store authorization credentials. def get_authenticated_service (): flow = InstalledAppFlow . from_client_secrets_file ( CLIENT_SECRETS_FILE , SCOPES ) credentials = flow . run_console () return build ( API_SERVICE_NAME , API_VERSION , credentials = credentials ) # Remove keyword arguments that are not set. def remove_empty_kwargs ( ** kwargs ): good_kwargs = {} if kwargs is not None : for key , value in kwargs . iteritems (): if value : good_kwargs [ key ] = value return good_kwargs # Call the YouTube Reporting API's reportTypes.list method to retrieve report types. def list_report_types ( youtube_reporting , ** kwargs ): # Provide keyword arguments that have values as request parameters. kwargs = remove_empty_kwargs ( ** kwargs ) results = youtube_reporting . reportTypes () . list ( ** kwargs ) . execute () reportTypes = results [ 'reportTypes' ] if 'reportTypes' in results and results [ 'reportTypes' ]: reportTypes = results [ 'reportTypes' ] for reportType in reportTypes : print 'Report type id: %s \n name: %s \n ' % ( reportType [ 'id' ], reportType [ 'name' ]) else : print 'No report types found' return False return True # Call the YouTube Reporting API's jobs.create method to create a job. def create_reporting_job ( youtube_reporting , report_type_id , ** kwargs ): # Provide keyword arguments that have values as request parameters. kwargs = remove_empty_kwargs ( ** kwargs ) reporting_job = youtube_reporting . jobs () . create ( body = dict ( reportTypeId = args . report_type , name = args . name ), ** kwargs ) . execute () print ( 'Reporting job " %s " created for reporting type " %s " at " %s "' % ( reporting_job [ 'name' ], reporting_job [ 'reportTypeId' ], reporting_job [ 'createTime' ])) # Prompt the user to enter a report type id for the job. Then return the id. def get_report_type_id_from_user (): report_type_id = raw_input ( 'Please enter the reportTypeId for the job: ' ) print ( 'You chose " %s " as the report type Id for the job.' % report_type_id ) return report_type_id # Prompt the user to set a job name def prompt_user_to_set_job_name (): job_name = raw_input ( 'Please set a name for the job: ' ) print ( 'Great! " %s " is a memorable name for this job.' % job_name ) return job_name if __name__ == '__main__' : parser = argparse . ArgumentParser () # The 'name' option specifies the name that will be used for the reporting job. parser . add_argument ( '--content-owner' , default = '' , help = 'ID of content owner for which you are retrieving jobs and reports.' ) parser . add_argument ( '--include-system-managed' , default = False , help = 'Whether the API response should include system-managed reports' ) parser . add_argument ( '--name' , default = '' , help = 'Name for the reporting job. The script prompts you to set a name ' + 'for the job if you do not provide one using this argument.' ) parser . add_argument ( '--report-type' , default = None , help = 'The type of report for which you are creating a job.' ) args = parser . parse_args () youtube_reporting = get_authenticated_service () try : # Prompt user to select report type if they didn't set one on command line. if not args . report_type : if list_report_types ( youtube_reporting , onBehalfOfContentOwner = args . content_owner , includeSystemManaged = args . include_system_managed ): args . report_type = get_report_type_id_from_user () # Prompt user to set job name if not set on command line. if not args . name : args . name = prompt_user_to_set_job_name () # Create the job. if args . report_type : create_reporting_job ( youtube_reporting , args , onBehalfOfContentOwner = args . content_owner ) except HttpError , e : print 'An HTTP error %d occurred: \n %s ' % ( e . resp . status , e . content )