העלה סרטונים

‫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 קובעים מי יכול לראות את הסרטון שהועלה. ‫enum‏ YouTubeVideoPrivacy תומך בערכים הבאים:

  • ‫PUBLIC: הסרטון זמין לכל אחד ב-YouTube. (מותר רק בערוצי מותג).
  • ‫UNLISTED: אי אפשר לחפש את הסרטון, אבל כל מי שיש לו את הקישור יכול לצפות בו. זוהי אפשרות ברירת המחדל והאפשרות היחידה לערוצים שמנוהלים על ידי Google.

העלאת סרטון

כדי להעלות סרטון, צריך להשתמש בבקשה מרובת חלקים לשיטה CreateYouTubeVideoUpload. הבקשה מכילה גם את המטא-נתונים של ההעלאה וגם את קובץ הווידאו עצמו.

1. הפעלת ההעלאה

יוצרים CreateYouTubeVideoUploadRequest ומציינים את:

  • ‫customer_id: מספר הלקוח ב-Google Ads.
  • ‫you_tube_video_upload: אובייקט מסוג YouTubeVideoUpload עם המאפיינים video_title, ‏ video_description, ועם המאפיינים channel_id ו-video_privacy (לא חובה).

אם משתמשים בספריית לקוח, קוראים לשיטה 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 להעלאה שניתן להמשיך.

אפשר גם להצהיר על הגודל של הסרטון שאתם מתכוונים להעלות בהתחלה, כשמתחילים את התהליך, באמצעות כותרת בקשת ה-HTTP‏ x-goog-upload-header-content-length.

לתיאור מלא של כותרות ה-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.