Videos hochladen

Mit der YouTubeVideoUploadService können Sie Videos direkt über die Google Ads API auf YouTube hochladen. Diese Videos können dann als Assets in verschiedenen Anzeigentypen verwendet werden, z. B. in Performance Max-Kampagnen oder Demand Gen-Kampagnen.

Dieser Dienst vereinfacht den Workflow für die Erstellung von Videoanzeigen, da er den YouTube-Uploadprozess übernimmt und dafür sorgt, dass die Videos korrekt mit Ihrem Konto verknüpft werden.

Wichtige Konzepte

Bevor Sie beginnen, sollten Sie wissen, wie Video-Uploads verwaltet werden und welche verschiedenen Status sie durchlaufen können.

Kanalzugehörigkeit

Wenn du ein Video hochlädst, kannst du den Ziel-YouTube-Kanal mit dem Feld channel_id in der Ressource YouTubeVideoUpload angeben:

  • Kanal des Werbetreibenden (Markenkanal):Geben Sie die channel_id eines YouTube-Kanals an, der dem Werbetreibenden gehört. Wenn du Videos auf einen Markenkanal hochlädst, hast du mehr Kontrolle über die Datenschutzeinstellungen und die Sichtbarkeit des Videos.
  • Von Google verwalteter Kanal:Wenn channel_id ausgelassen wird, wird das Video in einen von Google verwalteten YouTube-Kanal hochgeladen, der mit dem Google Ads-Konto verknüpft ist.

Uploadstatus

Der Lebenszyklus eines YouTube-Video-Uploads wird über das Feld state verfolgt. Das YouTubeVideoUploadState-Enum definiert die folgenden Status:

Bundesland Beschreibung
PENDING Das Video wird hochgeladen.
UPLOADED Das Video wurde hochgeladen und wird von YouTube verarbeitet.
PROCESSED Das Video wurde erfolgreich verarbeitet und kann verwendet werden.
FAILED Der Upload oder die Verarbeitung ist fehlgeschlagen und kann nicht abgeschlossen werden.
REJECTED Das Video wurde aus Validierungs- oder Richtliniengründen abgelehnt.
UNAVAILABLE Der Videostatus ist nicht verfügbar. Das Video wurde möglicherweise von YouTube entfernt.

Datenschutzeinstellungen

Im Feld video_privacy kannst du festlegen, wer das hochgeladene Video sehen darf. Die YouTubeVideoPrivacy-Enumeration unterstützt:

  • PUBLIC: Das Video ist für alle auf YouTube verfügbar. (Nur für Markenkanäle zulässig)
  • UNLISTED: Das Video ist nicht in der Suche zu finden, kann aber von allen mit dem Link angesehen werden. Dies ist die Standardeinstellung und die einzige Option für von Google verwaltete Channels.

Video hochladen

Wenn Sie ein Video hochladen möchten, müssen Sie eine mehrteilige Anfrage an die Methode CreateYouTubeVideoUpload senden. Die Anfrage enthält sowohl die Metadaten für den Upload als auch die Videodatei selbst.

1. Upload starten

Erstellen Sie ein CreateYouTubeVideoUploadRequest mit folgenden Angaben:

  • customer_id: Ihre Google Ads-Kundennummer.
  • you_tube_video_upload: Ein YouTubeVideoUpload-Objekt mit video_title, video_description und optional channel_id und video_privacy.

Wenn Sie eine Clientbibliothek verwenden, rufen Sie die Methode CreateYouTubeVideoUpload auf und übergeben Sie Ihre Videodatei. Der Video-Upload wird dann intern verarbeitet.

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

Wenn Sie REST verwenden, wird im folgenden Abschnitt beschrieben, wie Sie den Video-Upload verwalten.

2. Video hochladen

Wenn Sie eine REST-Anfrage an die Methode CreateYouTubeVideoUpload senden, enthält die Antwort im HTTP-Antwortheader x-goog-upload-url die URL, die zum Hochladen der Videobyte verwendet werden soll, sowie andere Metadaten wie die erwartete Größe der einzelnen Chunks für Chunked Uploads.

Sie können die Größe des Videos, das Sie hochladen möchten, auch zu Beginn des Prozesses mit dem HTTP-Request-Header x-goog-upload-header-content-length deklarieren.

Eine vollständige Beschreibung der im Videouploadprotokoll verwendeten HTTP-Header finden Sie im folgenden Codebeispiel:

# 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. Status des Video-Uploads abrufen

Nachdem Sie einen Video-Upload gestartet haben, können Sie den Status abrufen, indem Sie die Ressource you_tube_video_upload mit GAQL abfragen:

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

Uploads verwalten

Nachdem ein Video hochgeladen wurde, können Sie es als Video-Asset verwenden.

Hochgeladenes Video verwenden

Sobald ein Video den Status PROCESSED erreicht hat, finden Sie seine YouTube-Video-ID im Feld video_id der YouTubeVideoUpload-Ressource.

Mit diesem video_id können Sie ein VideoAsset erstellen oder es direkt mit Anzeigentypen verknüpfen, die YouTube-Videos unterstützen. Dazu müssen Sie die Video-ID angeben.

Metadaten aktualisieren

Du kannst die Metadaten eines über diese API hochgeladenen Videos mit der Methode UpdateYouTubeVideoUpload aktualisieren. Nur die Felder video_title, video_description und video_privacy können aktualisiert werden.

Uploads entfernen

Wenn Sie Videos löschen möchten, die mit der Google Ads API hochgeladen wurden, verwenden Sie die Methode RemoveYouTubeVideoUpload. Dadurch wird das Video sowohl aus der Google Ads-Asset-Bibliothek als auch von YouTube entfernt.

Zurück
Assets für Business Messages
Weiter
Berichterstellung