אתם מוזמנים להצטרף אלינו לשידור חי ב-Discord בשרת של קהילת Google בנושא פרסום ומדידה, וב-YouTube ב-26 בפברואר בשעה 17:00 (שעון ישראל). במאמר הזה נסביר על התכונות החדשות שנוספו לגרסה 23.1 של Google Ads API.

העלה סרטונים

‫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#‎

This example is not yet available in C#; you can take a look at the other languages.

PHP

This example is not yet available in PHP; you can take a look at the other languages.

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,
        )
    )
    print(f"Created YouTube video upload: {response.resource_name}")upload_video.py

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 "developer-token: ${DEVELOPER_TOKEN}" \
--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')upload_video.sh

אם אתם משתמשים ב-REST, בקטע הבא מוסבר איך לנהל את העלאת הסרטון.

2. העלאת הסרטון

כששולחים בקשת REST לשיטה CreateYouTubeVideoUpload, התשובה מכילה את כתובת ה-URL שבה צריך להשתמש כדי להעלות את בייטים של הסרטון בכותרת התגובה של HTTP x-goog-upload-url, יחד עם מטא-נתונים אחרים כמו הגודל הצפוי של כל נתח בהעלאות של נתחים.

אתם יכולים גם להצהיר על גודל הסרטון שאתם עומדים להעלות בהתחלה, כשמתחילים את התהליך, באמצעות כותרת בקשת ה-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')upload_video.sh

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#‎

This example is not yet available in C#; you can take a look at the other languages.

PHP

This example is not yet available in PHP; you can take a look at the other languages.

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}."
    )upload_video.py

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'"
}
EOFupload_video.sh

נהל העלאות

אחרי שמעלים סרטון, אפשר להשתמש בו כנכס וידאו.

שימוש בסרטון שהועלה

אחרי שסרטון מגיע למצב PROCESSED, אפשר למצוא את מזהה הסרטון ב-YouTube בשדה video_id של משאב YouTubeVideoUpload.

אפשר להשתמש בvideo_id כדי ליצור VideoAsset או לקשר אותו ישירות לסוגי מודעות שתומכים בסרטוני YouTube באמצעות הפניה למזהה הסרטון.

עדכון של מטא-נתונים

אפשר לעדכן את המטא-נתונים של סרטון שהועלה דרך ה-API הזה באמצעות השיטה UpdateYouTubeVideoUpload. אפשר לעדכן רק את השדות video_title, video_description ו-video_privacy.

הסרת העלאות

אם אתם צריכים למחוק סרטונים שהועלו באמצעות Google Ads API, אתם יכולים להשתמש בשיטה RemoveYouTubeVideoUpload. הסרטון יוסר גם מספריית הנכסים הדיגיטליים של Google Ads וגם מ-YouTube.

נכסי שליחת הודעות לעסק

דיווח

העלה סרטונים קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מושגים מרכזיים

בעלות על ערוץ

מצבי העלאה

הגדרות פרטיות

העלאת סרטון

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

Java

C#‎

PHP

Python

Ruby

Perl

curl

2. העלאת הסרטון

3. אחזור מצב ההעלאה של הסרטון

Java

C#‎

PHP

Python

Ruby

Perl

curl

נהל העלאות

שימוש בסרטון שהועלה

עדכון של מטא-נתונים

הסרת העלאות

העלה סרטונים