YouTubeVideoUploadService מאפשר לכם להעלות סרטונים ישירות ל-YouTube דרך Google Ads API. אחר כך אפשר להשתמש בסרטונים האלה כדי ליצור נכסי וידאו בסוגים שונים של מודעות, כמו קמפיינים למיקסום הביצועים או קמפיינים ליצירת ביקוש.
השירות הזה מייעל את תהליך העבודה של יצירת מודעות וידאו. הוא מטפל בתהליך ההעלאה ל-YouTube, ומבטיח שהסרטונים ישויכו לחשבון שלכם בצורה נכונה.
מושגים מרכזיים
לפני שמתחילים, חשוב להבין איך מתנהלת העלאת סרטונים ואת המצבים השונים שהם יכולים לעבור.
בעלות על ערוץ
כשאתם מעלים סרטון, אתם יכולים לציין את ערוץ YouTube היעד באמצעות השדה channel_id במשאב YouTubeVideoUpload:
- ערוץ בבעלות המפרסם (מותג): צריך לציין את
channel_idשל ערוץ YouTube קיים שבבעלות המפרסם. האפשרות הזו נתמכת רק בתהליך אימות המשתמש, ואי אפשר להשתמש בה עם חשבונות שירות. - ערוץ בניהול Google: אם לא מציינים את
channel_id, הסרטון מועלה לערוץ YouTube בניהול Google שמשויך לחשבון Google Ads.
סטטוסים של העלאות
מחזור החיים של העלאת סרטון ל-YouTube מתועד בשדה state.
ה-enum YouTubeVideoUploadState מגדיר את הסטטוסים הבאים:
| מדינה (State) | תיאור |
|---|---|
PENDING |
הסרטון בתהליך העלאה. |
UPLOADED |
הסרטון הועלה בהצלחה ועובר עיבוד ב-YouTube. |
PROCESSED |
העיבוד של הסרטון הסתיים והוא מוכן לשימוש. |
FAILED |
ההעלאה או העיבוד נכשלו ואי אפשר להשלים אותם. |
REJECTED |
הסרטון נדחה בגלל בעיות באימות או בגלל הפרות מדיניות. |
UNAVAILABLE |
מצב הסרטון הוא 'לא זמין'. יכול להיות שהסרטון הוסר מ-YouTube. |
הגדרות פרטיות
השדה video_privacy קובע מי יכול לראות את הסרטון שהועלה. הערכים האפשריים של YouTubeVideoPrivacy הם:
PUBLIC: הסרטון זמין לכולם ב-YouTube. (מותר רק בערוצי מותג).-
UNLISTED: אי אפשר לחפש את הסרטון, אבל כל מי שיש לו את הקישור יכול לצפות בו. זוהי אפשרות ברירת המחדל והאפשרות היחידה לערוצים שמנוהלים על ידי Google.
גילוי נאות לגבי תוכן שנוצר על ידי AI
החל מגרסה 26, בהתאם לתקנות כמו EU AI Act (חוק הבינה המלאכותית של האיחוד האירופי), מפרסמים יכולים לציין אם קטע וידאו שהועלה מכיל תוכן שנוצר על ידי AI או מדיה סינתטית.
השדה video_content_metadata ב-YouTubeVideoUpload מכיל את הערך VideoContentMetadata. מגדירים את השדה המקונן generative_content_disclosure באמצעות הערך YouTubeVideoUploadGenerativeContentDisclosure enum:
| ערך | תיאור |
|---|---|
NON_GENERATIVE_CONTENT |
המפרסם ציין שהסרטון לא נוצר על ידי AI. |
GENERATIVE_CONTENT |
המפרסם ציין שהסרטון נוצר על ידי AI. |
העלאת סרטון
כדי להעלות סרטון, צריך להשתמש בבקשה מרובת חלקים לשיטה CreateYouTubeVideoUpload. הבקשה מכילה גם את המטא-נתונים של ההעלאה וגם את קובץ הווידאו עצמו.
1. התחלת ההעלאה
יוצרים CreateYouTubeVideoUploadRequest ומציינים את:
-
customer_id: מספר הלקוח ב-Google Ads. -
you_tube_video_upload: אובייקטYouTubeVideoUploadעםvideo_title, video_description, ואופציונליתchannel_id,video_privacy, והחל מגרסה 26,video_content_metadata.
אם אתם משתמשים בספריית לקוח, צריך להפעיל את ה-method CreateYouTubeVideoUpload, להעביר את קובץ הווידאו והעלאת הסרטון תטופל באופן פנימי.
Java
This example is not yet available in Java; you can take a look at the other languages.
C#
YouTubeVideoUploadServiceClient ytService = client.GetService( Services.V25.YouTubeVideoUploadService); CreateYouTubeVideoUploadRequest createUploadRequest = new CreateYouTubeVideoUploadRequest() { CustomerId = customerId.ToString(), YouTubeVideoUpload = new YouTubeVideoUpload() { VideoTitle = "Test Video", VideoDescription = "Test Video Description", VideoPrivacy = YouTubeVideoPrivacy.Unlisted } }; string videoUploadResourceName; using (FileStream stream = File.OpenRead(videoFilePath)) { ResumableUploadSession<CreateYouTubeVideoUploadRequest, CreateYouTubeVideoUploadResponse> session = ytService.CreateYouTubeVideoUpload(); CreateYouTubeVideoUploadResponse response = session.BeginUploadAsync(createUploadRequest, stream).Result; videoUploadResourceName = response.ResourceName; Console.WriteLine($"Created YouTube video upload: {videoUploadResourceName}"); }
PHP
$youTubeVideoUploadServiceClient = $googleAdsClient->getYouTubeVideoUploadServiceClient(); $youTubeVideoUpload = new YouTubeVideoUpload([ 'video_title' => 'Test Video', 'video_description' => 'Test Video Description', 'video_privacy' => YouTubeVideoPrivacy::UNLISTED ]); $createYouTubeVideoUploadRequest = CreateYouTubeVideoUploadRequest::build( $customerId, $youTubeVideoUpload ); /** @var ResumableUpload $resumableUpload */ $resumableUpload = $youTubeVideoUploadServiceClient->createYouTubeVideoUpload( $createYouTubeVideoUploadRequest ); $stream = Utils::streamFor(fopen($videoFilePath, 'rb')); /** @var CreateYouTubeVideoUploadResponse $response */ $response = $resumableUpload->startUpload($stream); $videoUploadResourceName = $response->getResourceName(); printf("Created YouTube video upload: '%s'%s", $videoUploadResourceName, PHP_EOL);
Python
yt_service: YouTubeVideoUploadServiceClient = client.get_service( "YouTubeVideoUploadService" ) create_upload_request: CreateYouTubeVideoUploadRequest = ( youtube_video_upload_service.CreateYouTubeVideoUploadRequest() ) create_upload_request.customer_id = customer_id create_upload_request.you_tube_video_upload.video_title = "Test Video" create_upload_request.you_tube_video_upload.video_description = ( "Test Video Description" ) create_upload_request.you_tube_video_upload.video_privacy = ( client.enums.YouTubeVideoPrivacyEnum.UNLISTED ) video_upload_resource_name: str with open(video_file_path, "rb") as stream: response: CreateYouTubeVideoUploadResponse = ( yt_service.create_you_tube_video_upload( stream=stream, request=create_upload_request, retry=None, ) ) video_upload_resource_name = response.resource_name print(f"Created YouTube video upload: {video_upload_resource_name}")
Ruby
This example is not yet available in Ruby; you can take a look at the other languages.
Perl
This example is not yet available in Perl; you can take a look at the other languages.
curl
# # Use the --i curl parameter to capture response headers in the $RESPONSE # variable. FILE_SIZE=$(wc -c < "${VIDEO_FILE_NAME}" | tr -d '\r') RESPONSE=$(curl -i -f -v -s --request POST \ "https://googleads.googleapis.com/resumable/upload/v${API_VERSION}/customers/${CUSTOMER_ID}/youTubeVideoUploads:create" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --header "X-Goog-Upload-Protocol: resumable" \ --header "X-Goog-Upload-Command: start" \ --header "X-Goog-Upload-Header-Content-Length: ${FILE_SIZE}" \ --data @- <<EOF { "customer_id": "${CUSTOMER_ID}", "you_tube_video_upload": { "video_title": "${VIDEO_TITLE}", "video_description": "${VIDEO_DESCRIPTION}", "video_privacy": "UNLISTED" } } EOF ) # Extract the value of the "x-goog-upload-url" header from the HTTP response. UPLOAD_URL=$(echo "${RESPONSE}" \ | grep -i '^x-goog-upload-url' \ | awk '{print $2}' \ | tr -d '\r') CHUNK_SIZE=$(echo "${RESPONSE}" \ | grep -i '^x-goog-upload-chunk-granularity' \ | awk '{print $2}' \ | tr -d '\r')
אם אתם משתמשים ב-REST, בקטע הבא מוסבר איך לנהל את העלאת הסרטון.
2. העלאת הסרטון
כששולחים בקשת REST לשיטה CreateYouTubeVideoUpload, התשובה מכילה את כתובת ה-URL שבה צריך להשתמש כדי להעלות את בייטים של הסרטון בכותרת תגובת ה-HTTP x-goog-upload-url, יחד עם מטא-נתונים אחרים כמו הגודל הצפוי של כל נתח בהעלאות מחולקות, בהתאם לפרוטוקול הסטנדרטי של Google להעלאה שניתן להמשיך.
אתם יכולים גם להצהיר על הגודל של הסרטון שאתם מתכוונים להעלות בהתחלה, כשמתחילים את התהליך, באמצעות x-goog-upload-header-content-lengthכותרת בקשת ה-HTTP.
כדי לקבל תיאור מלא של כותרות ה-HTTP שמשמשות בפרוטוקול להעלאת סרטונים, אפשר לעיין בדוגמת הקוד הבאה:
# Take the first ${CHUNK_SIZE} bytes of the video file and upload them. head -c ${CHUNK_SIZE} ${VIDEO_FILE_NAME} | curl -i -v -X PUT "${UPLOAD_URL}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --header "X-Goog-Upload-Offset: 0" \ --header "X-Goog-Upload-Command: upload" \ --header "Content-Length: ${CHUNK_SIZE}" \ --data-binary @- # Query the status of the upload. QUERY_RESPONSE=$(curl -i -s -X POST "${UPLOAD_URL}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --header "X-Goog-Upload-Command: query") # Extract the value of the "x-goog-upload-size-received" header from the HTTP # response. UPLOADED_BYTES=$(echo "${QUERY_RESPONSE}" \ | grep -i '^x-goog-upload-size-received' \ | awk '{print $2}' \ | tr -d '\r') echo "Uploaded ${UPLOADED_BYTES} bytes." REMAINING_BYTES=$((FILE_SIZE - UPLOADED_BYTES)) echo "${REMAINING_BYTES} bytes remaining to upload." FINALIZE_RESPONSE=$(tail -c ${REMAINING_BYTES} ${VIDEO_FILE_NAME} | curl -v -X PUT "${UPLOAD_URL}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --header "X-Goog-Upload-Offset: ${UPLOADED_BYTES}" \ --header "X-Goog-Upload-Command: upload, finalize" \ --data-binary @-) UPLOADED_VIDEO_RESOURCE_NAME=$(echo $FINALIZE_RESPONSE | jq -r '.resourceName')
3. אחזור מצב ההעלאה של הסרטון
אחרי שמתחילים להעלות סרטון, אפשר לאחזר את המצב שלו על ידי שליחת שאילתה למשאב you_tube_video_upload באמצעות GAQL:
Java
This example is not yet available in Java; you can take a look at the other languages.
C#
// Retrieve the metadata of the newly uploaded video. string query = $@" SELECT you_tube_video_upload.resource_name, you_tube_video_upload.video_id, you_tube_video_upload.state FROM you_tube_video_upload WHERE you_tube_video_upload.resource_name = '{videoUploadResourceName}'"; GoogleAdsServiceClient gaService = client.GetService( Services.V25.GoogleAdsService); gaService.SearchStream(customerId.ToString(), query, delegate (SearchGoogleAdsStreamResponse resp) { foreach (GoogleAdsRow row in resp.Results) { Console.WriteLine( $"Video with ID {row.YouTubeVideoUpload.VideoId} was found in " + $"state {row.YouTubeVideoUpload.State}."); } } );
PHP
// Retrieve the metadata of the newly uploaded video. $query = sprintf( "SELECT you_tube_video_upload.resource_name, " . "you_tube_video_upload.video_id, " . "you_tube_video_upload.state " . "FROM you_tube_video_upload " . "WHERE you_tube_video_upload.resource_name = '%s'", $videoUploadResourceName ); $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); $stream = $googleAdsServiceClient->searchStream( SearchGoogleAdsStreamRequest::build($customerId, $query) ); foreach ($stream->iterateAllElements() as $googleAdsRow) { /** @var GoogleAdsRow $googleAdsRow */ printf( "Video with ID '%s' was found in state '%s'.%s", $googleAdsRow->getYouTubeVideoUpload()->getVideoId(), YouTubeVideoUploadState::name($googleAdsRow->getYouTubeVideoUpload()->getState()), PHP_EOL ); }
Python
# Retrieve the metadata of the newly uploaded video. query: str = f""" SELECT you_tube_video_upload.resource_name, you_tube_video_upload.video_id, you_tube_video_upload.state FROM you_tube_video_upload WHERE you_tube_video_upload.resource_name = '{video_upload_resource_name}'""" ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService") stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream( customer_id=customer_id, query=query ) for row in itertools.chain.from_iterable(batch.results for batch in stream): video = row.you_tube_video_upload print( f"Video with ID {row.you_tube_video_upload.video_id} was found in state {row.you_tube_video_upload.state}." )
Ruby
This example is not yet available in Ruby; you can take a look at the other languages.
Perl
This example is not yet available in Perl; you can take a look at the other languages.
curl
curl -i -v -X POST \ "https://qa-prod-googleads.sandbox.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "Developer-Token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "query": "SELECT you_tube_video_upload.resource_name, you_tube_video_upload.video_id, you_tube_video_upload.state FROM you_tube_video_upload WHERE you_tube_video_upload.resource_name = '$UPLOADED_VIDEO_RESOURCE_NAME'" } EOF
נהל העלאות
אחרי שהעלאת הסרטון מסתיימת, אפשר להשתמש בו כנכס וידאו.
שימוש בסרטון שהועלה
אחרי שהסרטון מגיע למצב PROCESSED, אפשר למצוא את מזהה הסרטון ב-YouTube בשדה video_id של המשאב YouTubeVideoUpload.
אפשר להשתמש ב-video_id כדי ליצור YoutubeVideoAsset עם MutateAssets, או לקשר אותו ישירות לסוגי מודעות שתומכים בסרטונים ב-YouTube באמצעות הפניה למזהה הסרטון.
עדכון של מטא-נתונים
אפשר לעדכן את המטא-נתונים של סרטון שהועלה באמצעות ה-API הזה, בעזרת השיטה UpdateYouTubeVideoUpload. אפשר לעדכן רק את השדות video_title, video_description ו-video_privacy.
הסרת העלאות
אם אתם צריכים למחוק סרטונים שהועלו באמצעות Google Ads API, אתם יכולים להשתמש בשיטה RemoveYouTubeVideoUpload. הסרטון יוסר גם מספריית הנכסים הדיגיטליים ב-Google Ads וגם מ-YouTube.