Method: spaces.setup

Erstellt einen Gruppenbereich und fügt die angegebenen Nutzer hinzu. Der aufrufende Nutzer wird automatisch dem Gruppenbereich hinzugefügt und sollte in der Anfrage nicht als Mitgliedschaft angegeben werden. Ein Beispiel finden Sie unter Gruppenbereich mit ersten Mitgliedern einrichten.

Wenn Sie die hinzuzufügenden menschlichen Mitglieder angeben möchten, fügen Sie Mitgliedschaften mit dem entsprechenden membership.member.name hinzu. Wenn Sie einen menschlichen Nutzer hinzufügen möchten, verwenden Sie users/{user}, wobei {user} die E-Mail-Adresse des Nutzers sein kann. Für Nutzer in derselben Google Workspace-Organisation kann {user} auch die id für die Person aus der People API oder die id für den Nutzer in der Directory API sein. Wenn die ID des Personenprofils der People API für user@example.com beispielsweise 123456789 ist, können Sie den Nutzer dem Gruppenbereich hinzufügen, indem Sie membership.member.name auf users/user@example.com oder users/123456789 festlegen.

Wenn Sie die hinzuzufügenden Google-Gruppen angeben möchten, fügen Sie Mitgliedschaften mit dem entsprechenden membership.group_member.name hinzu. Wenn Sie eine Google-Gruppe hinzufügen oder einladen möchten, verwenden Sie groups/{group}, wobei {group} die id für die Gruppe aus der Cloud Identity Groups API ist. Mit der Cloud Identity Groups Lookup API können Sie beispielsweise die ID 123456789 für die Gruppen-E-Mail-Adresse group@example.com abrufen und die Gruppe dann dem Gruppenbereich hinzufügen, indem Sie membership.group_member.name auf groups/123456789 festlegen. Gruppen-E-Mails werden nicht unterstützt und Google-Gruppen können nur als Mitglieder in benannten Gruppenbereichen hinzugefügt werden.

Wenn der Anrufer in einem benannten Gruppenbereich oder Gruppenchat einige Mitglieder blockiert oder von ihnen blockiert wird oder keine Berechtigung hat, einige Mitglieder hinzuzufügen, werden diese Mitglieder dem erstellten Gruppenbereich nicht hinzugefügt.

Wenn Sie eine Direktnachricht zwischen dem aufrufenden Nutzer und einem anderen menschlichen Nutzer erstellen möchten, geben Sie genau eine Mitgliedschaft an, die den menschlichen Nutzer darstellt. Wenn ein Nutzer den anderen blockiert, schlägt die Anfrage fehl und die Direktnachricht wird nicht erstellt.

Wenn Sie eine Direktnachricht zwischen dem aufrufenden Nutzer und der Anruf-App erstellen möchten, legen Sie Space.singleUserBotDm auf true fest und geben Sie keine Mitgliedschaften an. Mit dieser Methode können Sie nur eine DM mit der Anruf-App einrichten. Informationen zum Hinzufügen der Anruf-App als Mitglied eines Gruppenbereichs oder einer vorhandenen DM zwischen zwei menschlichen Nutzern finden Sie unter Nutzer oder App zu einem Gruppenbereich einladen oder hinzufügen.

Wenn bereits eine Direktnachricht zwischen zwei Nutzern vorhanden ist, wird die vorhandene Direktnachricht zurückgegeben, auch wenn ein Nutzer den anderen zum Zeitpunkt der Anfrage blockiert.

Gruppenbereiche mit Antworten mit Threads werden nicht unterstützt. Wenn Sie beim Einrichten eines Gruppenbereichs die Fehlermeldung ALREADY_EXISTS erhalten, versuchen Sie es mit einem anderen displayName. Ein vorhandener Gruppenbereich in der Google Workspace-Organisation verwendet möglicherweise bereits diesen Anzeigenamen.

Erfordert die Nutzerauthentifizierung mit einem der folgenden Autorisierungsbereiche:

  • https://www.googleapis.com/auth/chat.spaces.create
  • https://www.googleapis.com/auth/chat.spaces

HTTP-Anfrage

POST https://chat.googleapis.com/v1/spaces:setup

Die URL verwendet die Syntax der gRPC-Transcodierung.

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung 
{
  "space": {
    object (Space)
  },
  "requestId": string,
  "memberships": [
    {
      object (Membership)
    }
  ]
}
Felder
space

object (Space)

Erforderlich. Das Feld Space.spaceType ist erforderlich.

Wenn Sie einen Gruppenbereich erstellen möchten, legen Sie Space.spaceType auf SPACE und Space.displayName fest. Wenn Sie beim Einrichten eines Gruppenbereichs die Fehlermeldung ALREADY_EXISTS erhalten, versuchen Sie es mit einem anderen displayName. Ein vorhandener Gruppenbereich in der Google Workspace-Organisation verwendet möglicherweise bereits diesen Anzeigenamen.

Wenn Sie einen Gruppenchat erstellen möchten, legen Sie Space.spaceType auf GROUP_CHAT fest. Legen Sie Space.displayName nicht fest.

Wenn Sie eine 1:1-Unterhaltung zwischen Personen erstellen möchten, legen Sie Space.spaceType auf DIRECT_MESSAGE und Space.singleUserBotDm auf false fest. Legen Sie Space.displayName oder Space.spaceDetails nicht fest.

Wenn Sie eine 1:1-Unterhaltung zwischen einer Person und der aufrufenden Chat-App erstellen möchten, legen Sie Space.spaceType auf DIRECT_MESSAGE und Space.singleUserBotDm auf true fest. Legen Sie Space.displayName oder Space.spaceDetails nicht fest.

Wenn bereits ein DIRECT_MESSAGE-Gruppenbereich vorhanden ist, wird dieser zurückgegeben, anstatt einen neuen zu erstellen.
requestId

string

Optional. Eine eindeutige ID für diese Anfrage. Eine zufällige UUID wird empfohlen. Wenn Sie eine Anfrage-ID angeben, wird die Anfrage idempotent. So wird sichergestellt, dass bei mehreren identischen Anfragen mit derselben Anfrage-ID nur ein einziger Gruppenbereich erstellt wird. Bei nachfolgenden Anfragen mit derselben Anfrage-ID wird der vorhandene Gruppenbereich zurückgegeben und nicht aktualisiert, auch wenn sich die angeforderten Details vom aktuellen Status unterscheiden.

So verwenden Sie dieses Feld effektiv:

  • Achten Sie darauf, dass nachfolgende Anfragen identisch sind und dieselben Authentifizierungsdaten wie die ursprüngliche Anfrage verwenden.
  • Wenn mit der angegebenen Anfrage-ID bereits ein Gruppenbereich erstellt wurde, wird dieser von der Anfrage zurückgegeben. Der zurückgegebene Gruppenbereich ist möglicherweise nicht vollständig ausgefüllt. Die API gibt den Gruppenbereich in Ihrer Anfrage mit dem vom System zugewiesenen Ressourcennamen zurück. Rufen Sie spaces.get auf, um die neuesten Metadaten für den Gruppenbereich abzurufen.
  • Wenn Sie eine vorhandene Anfrage-ID mit einem anderen authentifizierten Nutzer wiederverwenden, führt dies zu einem Fehler.
memberships[]

object (Membership)

Optional. Die Google Chat-Nutzer oder -Gruppen, die Sie einladen möchten, dem Gruppenbereich beizutreten. Lassen Sie den aufrufenden Nutzer weg, da er automatisch hinzugefügt wird.

Derzeit sind bis zu 49 Mitgliedschaften zulässig (zusätzlich zum Anrufer).

Bei einer menschlichen Mitgliedschaft muss das Membership.member Feld einen user mit ausgefülltem name (Format: users/{user}) und type auf User.Type.HUMAN enthalten. Sie können nur menschliche Nutzer hinzufügen, wenn Sie einen Gruppenbereich einrichten. Das Hinzufügen von Chat-Apps wird nur für die Einrichtung von Direktnachrichten mit der Anruf-App unterstützt. Sie können auch Mitglieder hinzufügen, indem Sie die E-Mail-Adresse des Nutzers als Alias für {user} verwenden. Der user.name kann beispielsweise users/example@gmail.com sein. Wenn Sie Gmail-Nutzer oder Nutzer aus externen Google Workspace-Domains einladen möchten, muss die E-Mail-Adresse des Nutzers für {user} verwendet werden.

Bei einer Google-Gruppenmitgliedschaft muss das Feld Membership.group_member eine group mit ausgefülltem name (Format: groups/{group}) enthalten. Sie können nur Google-Gruppen hinzufügen, wenn Sie Space.spaceType auf SPACE festlegen.

Optional, wenn Sie Space.spaceType auf SPACE festlegen.

Erforderlich, wenn Sie Space.spaceType auf GROUP_CHAT festlegen, zusammen mit mindestens zwei Mitgliedschaften.

Erforderlich, wenn Sie Space.spaceType auf DIRECT_MESSAGE mit einem menschlichen Nutzer festlegen, zusammen mit genau einer Mitgliedschaft.

Muss leer sein, wenn Sie eine 1:1-Unterhaltung zwischen einer Person und der aufrufenden Chat-App erstellen (wenn Sie Space.spaceType auf DIRECT_MESSAGE und Space.singleUserBotDm auf true festlegen).

Antworttext

Wenn der Vorgang erfolgreich abgeschlossen wurde, enthält der Antworttext eine Instanz von Space.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.create

Weitere Informationen finden Sie im Autorisierungsleitfaden.