Google Chat API'yi kullanarak mesajları aktarma

Bu kılavuzda, Chat API'deki StreamMessage kaynağını kullanarak Google Chat'te mesajların nasıl kademeli olarak yayınlanacağı açıklanmaktadır. Akış, Google Chat uygulamanızın canlı ilerleme göstergelerini, ara akıl yürütme veya araç yürütme adımlarını ve bir mesajı tamamlamadan önce artımlı metin yanıtlarını görüntülemesine olanak tanır.

Akış, üretken yapay zeka tarafından desteklenen Chat uygulamaları veya eksiksiz bir yanıt oluşturmanın birkaç saniye ya da dakika sürdüğü uzun süreli arka uç iş akışları için tasarlanmıştır.

Mesaj akışının işleyiş şekli

Akış mesajı, bir alanda standart bir Message kaynağı olmadan önce etkin bir akış durumundan geçer:

  1. Akış başlatma (spaces.streamMessages.create): Chat uygulamanız, yanıtladığı kullanıcı etkileşimi mesajına referans vererek mesaj dizisine dayalı bir alanda StreamMessage oluşturur. API, ileti dizisinde canlı bir ilerleme göstergesi gösterir ve bir StreamMessage kaynak adı ile ilk nextChunkToken değerini döndürür.
  2. Akışı güncelleme (appendStreamMessageContent veya patch): Chat uygulamanız çıkış oluştururken en son nextChunkToken değerini kullanarak sıralı güncellemeler gönderir:
    • Yeni metin parçalarını birleştirmek, ara adımlar eklemek, satır içi alıntılar eklemek veya progressText değerini güncellemek için spaces.streamMessages.appendStreamMessageContent yöntemini çağırın.
    • Akışla aktarılan içerik parçalarını değiştirmek için spaces.streamMessages.patch yöntemini çağırın veya progressText yöntemini yerinde güncelleyin.
  3. Canlı yayını sonlandırma veya silme (commit veya delete):
    • Akışı sonlandırmak ve kalıcı bir Message kaynağına dönüştürmek için spaces.streamMessages.commit yöntemini çağırın. Onaylama sırasında kartlar, aksesuar widget'ları ve altbilgi kaynakları gibi yalnızca onaylama öğeleri de ekleyebilirsiniz.
    • Alanda mesaj kaydetmeden etkin bir akışı silmek için spaces.streamMessages.delete yöntemini çağırın.

Bir akış etkinken yalnızca akışın yapıldığı referans mesajın (referencedMessage) göndereni, oluşturma işlemini iptal etmek için Durdur'u tıklayabilir. Chat, Chat uygulamanıza bir iptal sistemi komut etkinliği gönderir. Böylece arka uç çalışmasını durdurabilir ve kısmi çıkışı uygulayabilir ya da akışı silebilirsiniz.

Ön koşullar

Chat API ile mesaj akışı oluşturmak için aşağıdaki ön koşulları tamamlayın:

  • Google Chat'e erişimi olan bir Business veya Enterprise Google Workspace hesabı.
  • Ortamınızı ayarlama:
  • Chat uygulamanızı mesaj dizisi biçimli bir Chat alanına (veya en az bir mesaj içeren bire bir doğrudan mesaja) ekleyin ve yanıtlanacak erişilebilir bir mesajın (spaces/SPACE_ID/messages/MESSAGE_ID) kaynak adını alın.

  • Python örnekleri için Python ve google-auth için Google API İstemci Kitaplığı'nı yükleyin ve Chat API hizmet istemcisini ilk kullanıma hazırlayın:

    pip install google-api-python-client google-auth
    from google.oauth2 import service_account
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/chat.bot"]
creds = service_account.Credentials.from_service_account_file(
    "credentials.json", scopes=SCOPES
)
chat = build("chat", "v1", credentials=creds)

Akış başlatma

Yanıtı akış şeklinde göstermeye başlamak için spaces.streamMessages.create yöntemini çağırın ve istek gövdesinde bir StreamMessage iletin:

  • referencedMessage (Zorunlu): Yanıtı tetikleyen mesajın kaynak adı. spaces/{space}/messages/{message} olarak biçimlendirilir. Referans verilen mesaj aynı alana ait olmalı ve Chat uygulamanız tarafından erişilebilir olmalıdır. Chat, akışla aktarılan yanıtı referencedMessage ile aynı ileti dizisinde yayınlar.
  • progressText (Zorunlu): İlerleme göstergesinin yanında gösterilen, boş olmayan düz metin durum etiketi (en fazla 250 karakter), örneğin "Thinking...".
  • markupSyntax (İsteğe bağlı): Mesaj için MARKUP_SYNTAX_MARKDOWN veya MARKUP_SYNTAX_CHAT gibi metin biçimlendirme söz dizimi (MARKUP_SYNTAX_UNSPECIFIED ise varsayılan olarak Chat uygulamasının yapılandırılmış söz dizimi kullanılır). Satır içi alıntılar eklemeyi planlıyorsanız MARKUP_SYNTAX_MARKDOWN değerini ayarlayın.
  • streamContentChunks (İsteğe bağlı): Hemen gösterilecek ilk text, step veya citation parçaları.

Sonraki çağrılar için yanıttan hem name (spaces/{space}/streamMessages/{stream_message}) hem de nextChunkToken değerini kaydedin.

HTTP

POST https://chat.googleapis.com/v1/spaces/SPACE_ID/streamMessages HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "referencedMessage": "spaces/SPACE_ID/messages/MESSAGE_ID",
  "progressText": "Thinking...",
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN"
}

Python

stream = (
    chat.spaces()
    .streamMessages()
    .create(
        parent="spaces/SPACE_ID",
        body={
            "referencedMessage": "spaces/SPACE_ID/messages/MESSAGE_ID",
            "progressText": "Thinking...",
            "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
        },
    )
    .execute()
)

stream_name = stream["name"]
chunk_token = stream["nextChunkToken"]

Yöntem, bir StreamMessage kaynağı döndürür:

{
  "name": "spaces/SPACE_ID/streamMessages/STREAM_MESSAGE_ID",
  "progressText": "Thinking...",
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "nextChunkToken": "INITIAL_CHUNK_TOKEN"
}

İçerik parçaları ekleme

Chat uygulamanız ara adımlar veya metin jetonları oluştururken spaces.streamMessages.appendStreamMessageContent yöntemini çağırın:

  • chunkToken için en son nextChunkToken sürümünü geçin. Her başarılı çağrı, bir sonraki güncelleme veya kaydetme isteğinizde iletmeniz gereken yeni bir nextChunkToken döndürür.
  • text parçaları, daha önce akışla aktarılan metne doğrudan eklenir. Parçalar arasında gerektiğinde boşluk veya yeni satır ekleyin.
  • step parçaları, mesajda gösterilen ara adımlar listesine eklenir.

  • progressText isteğe bağlıdır. progressText parametresini atlarsanız veya "" değerine ayarlarsanız Chat, daha önce ayarlanan progressText değerini göstermeye devam eder.

HTTP

POST https://chat.googleapis.com/v1/spaces/SPACE_ID/streamMessages/STREAM_MESSAGE_ID:appendStreamMessageContent HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "chunkToken": "INITIAL_CHUNK_TOKEN",
  "progressText": "Searching documentation...",
  "streamContentChunks": [
    {
      "step": {
        "title": "Search knowledge base",
        "description": "Found 3 matching articles."
      }
    },
    {
      "text": "See <chat-citation data-id=\"c1\">guide</chat-citation>:\n"
    },
    {
      "citation": {
        "id": "c1",
        "citedSources": [
          {
            "title": "System Architecture Guide",
            "uri": "https://example.com/docs/arch"
          }
        ]
      }
    }
  ]
}

Python

stream = (
    chat.spaces()
    .streamMessages()
    .appendStreamMessageContent(
        name=stream_name,
        body={
            "chunkToken": chunk_token,
            "progressText": "Searching documentation...",
            "streamContentChunks": [
                {
                    "step": {
                        "title": "Search knowledge base",
                        "description": "Found 3 matching articles.",
                    }
                },
                {
                    "text": (
                        'See <chat-citation data-id="c1">'
                        "guide</chat-citation>:\n"
                    )
                },
                {
                    "citation": {
                        "id": "c1",
                        "citedSources": [
                            {
                                "title": "System Architecture Guide",
                                "uri": "https://example.com/docs/arch",
                            }
                        ],
                    }
                },
            ],
        },
    )
    .execute()
)

chunk_token = stream["nextChunkToken"]

Akışla aktarılan içeriği veya ilerleme metnini değiştirme

Daha önce akışla aktarılan içeriği yeniden yazmanız (ör. bir son işleme veya güvenlik filtresi çalıştırdıktan sonra) ya da parça eklemeden yalnızca progressText değerini güncellemeniz gerekiyorsa spaces.streamMessages.patch yöntemini çağırın:

  • updateMask parametresini, güncellenecek alanların virgülle ayrılmış listesi olarak ayarlayın: progressText, streamContentChunks veya progressText,streamContentChunks.
  • StreamMessage istek gövdesine en son nextChunkToken değerini ekleyin ve yanıtta döndürülen yeni nextChunkToken değerini kaydedin.
  • streamContentChunks, updateMask modundayken sağlanan parçalar, daha önce akışla aktarılan içeriğe eklenmek yerine bu içeriğin yerini alır.

  • progressText, updateMask olduğunda progressText, 250 karaktere kadar boş olmayan düz metin olmalıdır.

HTTP

PATCH https://chat.googleapis.com/v1/spaces/SPACE_ID/streamMessages/STREAM_MESSAGE_ID?updateMask=progressText,streamContentChunks HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "nextChunkToken": "LATEST_CHUNK_TOKEN",
  "progressText": "Formatting response...",
  "streamContentChunks": [
    {
      "text": "Updated response text."
    }
  ]
}

Python

stream = (
    chat.spaces()
    .streamMessages()
    .patch(
        name=stream_name,
        updateMask="progressText,streamContentChunks",
        body={
            "nextChunkToken": chunk_token,
            "progressText": "Formatting response...",
            "streamContentChunks": [
                {"text": "Updated response text."}
            ],
        },
    )
    .execute()
)

chunk_token = stream["nextChunkToken"]

Canlı yayını tamamlama

Oluşturma işlemi tamamlandığında, akışı kalıcı bir Message kaynağına dönüştürmek için en son chunkToken ile spaces.streamMessages.commit yöntemini çağırın:

  • İsteğe bağlı olarak, yalnızca onaylama parçası türleri (card, accessoryWidget ve citedSource) dahil olmak üzere onaylama isteğine son streamContentChunks ekleyebilirsiniz.

  • Önceki çağrılarda boş olmayan içerik yayınladıysanız onaylama sırasında streamContentChunks parametresini atlayabilirsiniz. Son kaydedilen mesaj boş olamaz.

HTTP

POST https://chat.googleapis.com/v1/spaces/SPACE_ID/streamMessages/STREAM_MESSAGE_ID:commit HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "chunkToken": "LATEST_CHUNK_TOKEN",
  "streamContentChunks": [
    {
      "text": "All checks passed."
    },
    {
      "citedSource": {
        "title": "Deployment Runbook",
        "uri": "https://example.com/docs/runbook"
      }
    },
    {
      "card": {
        "cardId": "details-card",
        "card": {
          "header": {
            "title": "Build Status"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "All 42 checks succeeded."
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Python

status_card = {
    "cardId": "details-card",
    "card": {
        "header": {"title": "Build Status"},
        "sections": [
            {
                "widgets": [
                    {"textParagraph": {"text": "All 42 checks succeeded."}}
                ]
            }
        ],
    },
}

commit_response = (
    chat.spaces()
    .streamMessages()
    .commit(
        name=stream_name,
        body={
            "chunkToken": chunk_token,
            "streamContentChunks": [
                {"text": "All checks passed."},
                {
                    "citedSource": {
                        "title": "Deployment Runbook",
                        "uri": "https://example.com/docs/runbook",
                    }
                },
                {"card": status_card},
            ],
        },
    )
    .execute()
)

final_message = commit_response["message"]
print(f"Committed message: {final_message['name']}")

Etkin bir akışı silme

Düzeltilemeyen bir hata oluşursa veya kullanıcı oluşturma işlemini iptal ederse ve mesaj dizisinde kısmi bir yanıt bırakmak istemiyorsanız spaces.streamMessages.delete yöntemini çağırın:

HTTP

DELETE https://chat.googleapis.com/v1/spaces/SPACE_ID/streamMessages/STREAM_MESSAGE_ID HTTP/1.1
Authorization: Bearer ACCESS_TOKEN

Python

chat.spaces().streamMessages().delete(name=stream_name).execute()

Bir akış Message içine kaydedildikten sonra, kesinleştirilmiş mesajı silmeniz gerekirse bunun yerine spaces.messages.delete yöntemini çağırın.

Desteklenen içerik parçası türleri

streamContentChunks içindeki her giriş, StreamContentChunk birleşimindeki bir alanı belirtir. Bazı parça türleri akış boyunca gönderilebilirken diğerleri yalnızca spaces.streamMessages.commit içinde kabul edilir:

Parça alanı Desteklenen yöntemler Son Message alanı Notlar
text create, appendStreamMessageContent, patch, commit text Artımlı metin. appendStreamMessageContent tarihinde birleştirildi; patch tarihinde değiştirildi. Nihai metin 32.000 baytı aşamaz.
step create, appendStreamMessageContent, patch, commit elements.steps.steps[] Düz metin title (gerekli) ve isteğe bağlı description içeren ara işleme adımı.
citation create, appendStreamMessageContent, patch, commit elements.citations[] Alfanümerik id (63 karakterden az, alt çizgi kullanılabilir) ve citedSources ile satır içi Citation. text içinde markupSyntax: "MARKUP_SYNTAX_MARKDOWN" ve eşleşen <chat-citation data-id="ID">...</chat-citation> etiketleri gerekir. Mevcut bir id ile citation göndermek, önceki alıntının üzerine yazılmasına neden olur.
card Yalnızca commit cardsV2[] Etkileşimli veya bilgilendirici CardWithId kart.
accessoryWidget Yalnızca commit accessoryWidgets[] İletinin altında gösterilen, geri bildirim düğmeleri gibi AccessoryWidget düğmeleri.
citedSource Yalnızca commit elements.citedSources[] Mesajın altında satır içi alıntı etiketleri olmadan gösterilen CitedSource altbilgi bağlantısı.

Kullanıcı tarafından başlatılan akış iptalini işleme

Bir akış etkinken yalnızca akışın yapıldığı referans mesajın (referencedMessage) göndereni, akış mesajında Durdur'u tıklayabilir. Kullanıcı bir akışı durdurduğunda Chat, Chat uygulamanızın uç noktasına cancelStream.streamMessage (durdurulan akışın spaces/{space}/streamMessages/{stream_message} kaynak adı) içeren bir sistem komutu etkileşim etkinliği gönderir.

Gelen JSON yükünün yapısı, Chat uygulamanızı Google Workspace eklentisi olarak mı yoksa Chat API etkileşim etkinliklerini kullanarak mı oluşturduğunuza bağlıdır:

Google Workspace eklentileri

{
  "commonEventObject": {
    "hostApp": "CHAT"
  },
  "chat": {
    "user": {
      "name": "users/USER_ID"
    },
    "space": {
      "name": "spaces/SPACE_ID"
    },
    "systemCommandPayload": {
      "systemCommandMetadata": {
        "cancelStream": {
          "streamMessage": "spaces/SPACE_ID/streamMessages/STREAM_ID"
        }
      }
    }
  }
}

Google Chat API

{
  "type": "SYSTEM_COMMAND",
  "space": {
    "name": "spaces/SPACE_ID"
  },
  "user": {
    "name": "users/USER_ID"
  },
  "systemCommandMetadata": {
    "cancelStream": {
      "streamMessage": "spaces/SPACE_ID/streamMessages/STREAM_ID"
    }
  }
}

Chat uygulamanız bir cancelStream etkinliği aldığında:

  1. Arka plan çalışanınıza, streamMessage için daha fazla jeton oluşturmayı veya alt araçları çalıştırmayı durdurması talimatını verin.
  2. Aşağıdaki yaklaşımlardan birini kullanarak etkin akışı çözün:
    • Kısmi çıkışı sakla: En son chunkToken ile spaces.streamMessages.commit işlevini çağırın (isteğe bağlı olarak "\n\n_Generation stopped._" gibi bir not ekleyin).
    • Yanıtı silme: İleti dizisine hiçbir şey kaydedilmemesi için spaces.streamMessages.delete yöntemini çağırın.
  3. Etkileşim etkinlik işleyicinizden boş bir HTTP 200 OK JSON yanıtı ({}) döndürün.

Sınırlamalar

Mesaj akışının aşağıdaki sınırlamaları vardır:

  • Platform kullanılabilirliği: Mesaj akışı yalnızca Chat'in web sürümünde görünür. Android ve iOS desteği yakında sunulacaktır.
  • Akış zaman aşımı: Etkin bir StreamMessage, oluşturulduktan 10 dakika sonra zaman aşımına uğrar. Chat uygulamanız, yayını başlattıktan sonraki 10 dakika içinde spaces.streamMessages.commit veya spaces.streamMessages.delete yöntemini çağırmalıdır.