Etapa 4: criar uma organização

Você criou uma conta e um projeto do Google Cloud e ativou as APIs. Agora você pode criar sua organização.

Pré-requisito

Para criar uma organização, é necessário atender a uma das seguintes condições:

ter uma conta do Google Cloud. Por padrão, uma conta do Google Cloud permite criar uma organização de avaliação não paga da Apigee. As organizações de avaliação expiram após 60 dias. Nesse momento, a organização será excluída.
Ter uma conta do Google Cloud e uma assinatura paga da Apigee ativada no projeto e na conta de faturamento do Google Cloud. Uma assinatura paga permite que você crie implementações completas e escalonáveis da Apigee. Entre em contato com a equipe de vendas da Apigee para comprar uma conta paga e ativar a assinatura.

Sobre a criação de organizações

Ao criar uma organização, vincule-a ao seu projeto do Google Cloud. O processo de vinculação de uma organização a um projeto do GCP é conhecido como provisionamento, que é apenas uma palavra sofisticada para configurar.

Ao provisionar uma organização, tenha em mente o seguinte:

Novo: não é possível provisionar uma organização atual da Apigee. Você precisa criar uma nova organização somente híbrida.
Familiar: uma organização híbrida é semelhante a uma organização Apigee tradicional, exceto pelo fato de estar vinculada a um projeto do Google Cloud. Não é o mesmo que uma organização do Google Cloud ou uma organização da Apigee.
Singular: é possível vincular um único projeto do Google Cloud a uma única organização da Apigee e vice-versa.

Depois de vincular uma nova organização com sucesso, é possível gerenciar usuários e papéis com o Console do Google Cloud enquanto você desenvolve, implanta e analisa os proxies de API com as APIs híbridas ou com a IU. Para mais informações sobre organizações, consulte Controle de versão e terminologia.

Para criar uma nova organização e provisioná-la:

Na linha de comando, receba as credenciais de autenticação de gcloud usando o comando a seguir:
Linux / MacOS
```
export TOKEN=$(gcloud auth print-access-token)
```
Para verificar se o token foi preenchido, use echo, como mostra o exemplo a seguir:
```
echo $TOKEN
```
Isso exibirá seu token como uma string codificada.
Windows
```
for /f "tokens=*" %a in ('gcloud auth print-access-token') do set TOKEN=%a
```
Para verificar se o token foi preenchido, use echo, como mostra o exemplo a seguir:
```
echo %TOKEN%
```
Isso exibirá seu token como uma string codificada.

Verifique se você tem as variáveis de ambiente necessárias definidas com os seguintes comandos:

echo ${PROJECT_ID}
echo ${ORG_NAME}
echo ${ORG_DISPLAY_NAME}
echo ${ORGANIZATION_DESCRIPTION}
echo ${ANALYTICS_REGION}
echo ${RUNTIMETYPE}

Se necessário, crie ou redefina as variáveis de ambiente a seguir para os elementos da organização. Elas serão usadas no comando para criar a organização.

PROJECT_ID (Required) é o projeto do Google Cloud que você quer vincular à sua nova organização com acesso híbrido. Este é o ID que o Google gerou para você na Etapa 2: criar um projeto do Google Cloud.
```
export PROJECT_ID=your_project_id
```
Observação: não inclua o ponto após o ID do projeto.
ORG_NAME (Obrigatório) é o ID programático que você quer para sua organização ativada para o híbrido.
Observação: o nome da organização precisa corresponder ao ID do projeto do Google Cloud.
```
export ORG_NAME=$PROJECT_ID
```
ORG_DISPLAY_NAME (Opcional) é o nome fácil de usar da organização. Esse valor não precisa ser exclusivo e pode incluir espaços e caracteres especiais. Por exemplo, "Minha organização híbrida".
```
ORG_DISPLAY_NAME="friendly_name"
```
O conteúdo do nome da variável que contém espaços precisa ser colocado entre aspas duplas. Por exemplo: "Minha organização"
ORGANIZATION_DESCRIPTION (Opcional) são informações sobre a organização que você quer usar como um lembrete da finalidade dela. Por exemplo, "Minha primeira organização".
```
ORGANIZATION_DESCRIPTION="description_text"
```

ANALYTICS_REGION (Obrigatório) é a região principal para o armazenamento de dados de análise.

export ANALYTICS_REGION=analytics_region

Em que analytics_region é um dos seguintes:

`asia-northeast1`	`asia-south1`	`asia-east1`	`asia-southeast1`
`australia-southeast1`	`us-central1`	`us-east1`	`us-west1`
`asia-southeast2`	`europe-west1`	`europe-west2`

Escolha uma região geograficamente próxima ou que atenda aos requisitos de armazenamento da organização.

RUNTIMETYPE (Obrigatório) é o tipo de ambiente de execução da organização da Apigee, em que HYBRID é o ambiente de execução híbrido da Apigee gerenciado pelo usuário.
```
export RUNTIMETYPE=HYBRID
```

Dica: use o comando echo $variable-name para verificar se as variáveis de ambiente estão definidas corretamente.

Envie uma solicitação POST autenticada para a API Create Organizations.
No exemplo a seguir, mostramos a estrutura de solicitação que cria uma organização:
```
curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json" \
  -d '{
    "name":"'"$ORG_NAME"'",
    "displayName":"'"$ORG_DISPLAY_NAME"'",
    "description":"'"$ORGANIZATION_DESCRIPTION"'",
    "runtimeType":"'"$RUNTIMETYPE"'",
    "analyticsRegion":"'"$ANALYTICS_REGION"'"
  }' \
  "https://apigee.googleapis.com/v1/organizations?parent=projects/$PROJECT_ID"
```
Dica: a estrutura das aspas ("'") no exemplo de código anterior é necessária para transmitir os valores das variáveis de ambiente no corpo do JSON.

Em uma solicitação de criação bem-sucedida, a API Organizations precisa responder com uma mensagem semelhante a esta:
```
{
  "name": "organizations/org_name/operations/LONG_RUNNING_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "INSERT",
    "targetResourceName": "organizations/org_name",
    "state": "IN_PROGRESS"
  }
}
```
Em que:
- LONG_RUNNING_OPERATION_ID é o UUID de uma operação assíncrona e de longa duração. É possível usar esse ID para verificar o status da solicitação de criação da organização (descrito na etapa 5).
- org_name é o ID da sua nova organização que está sendo criada.
Como a propriedade state na resposta indica que a Apigee começou a criar a nova organização, o estado dela é IN_PROGRESS. Esse processo pode levar vários minutos.

Se você receber um erro, consulte Como solucionar problemas na criação da organização.
Salve o ID da operação de longa duração em uma variável de ambiente. Ele será útil para tarefas de gerenciamento futuras.
Sintaxe
```
export LONG_RUNNING_OPERATION_ID=long_running_operation_ID
```
Exemplo
```
export LONG_RUNNING_OPERATION_ID=6abc8a72-46de-f9da-bcfe-70d9ab347e4f
```

É possível verificar o status da operação de longa duração com o ID que a Apigee retornou na solicitação de criação inicial. Para isso, use a API de operações. Exemplo:

curl -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/operations/$LONG_RUNNING_OPERATION_ID"

Os exemplos a seguir mostram possíveis respostas a essa solicitação:

IN_PROGRESS

Se a Apigee ainda estiver criando a organização, ela responderá com um status IN_PROGRESS. Exemplo:

{
  "name": "organizations/ORG_NAME/operations/LONG_RUNNING_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "INSERT",
    "targetResourceName": "organizations/ORG_NAME",
    "state": "IN_PROGRESS"
  }
}

Aguarde um pouco mais antes de tentar verificar se o processo de criação foi concluído.

FINISHED

Quando a organização foi provisionada, o estado da operação de longa duração era FINISHED. Exemplo:

{
  "name": "organizations/ORG_NAME/operations/LONG_RUNNING_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "INSERT",
    "targetResourceName": "organizations/ORG_NAME",
    "state": "FINISHED"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.Organization",
    "name": "ORG_NAME",
    "displayName": "ORG_DISPLAY_NAME",
    "description": "ORGANIZATION_DESCRIPTION",
    "createdAt": "1626237148461",
    "lastModifiedAt": "1626237149384",
    "properties": {
      "property": [
        {
          "name": "features.hybrid.enabled",
          "value": "true"
        },
        {
          "name": "features.mart.connect.enabled",
          "value": "true"
        }
      ]
    },
    "analyticsRegion": "ANALYTICS_REGION",
    "runtimeType": "HYBRID",
    "subscriptionType": "TRIAL",
    "state": "ACTIVE",
    "billingType": "EVALUATION",
    "expiresAt": "1631421073171",
    "addonsConfig": {
      "advancedApiOpsConfig": {},
      "integrationConfig": {},
      "monetizationConfig": {}
    }
  }
}

Se você não tiver inserido uma descrição, esse campo não aparecerá na resposta.

Visualizar os detalhes da organização

É possível visualizar os detalhes dos metadados da organização que você criou usando uma API da Apigee. Também é possível usar uma API para listar todas as organizações a que sua conta do Google Cloud tem acesso. Para executar essas ações, use a API Organizations.

Antes de testar as APIs, atualize o token de autorização:

TOKEN=$(gcloud auth print-access-token)

Acessar detalhes da organização

Para ver detalhes sobre uma única organização:

Envie uma solicitação GET (sem corpo) para o seguinte endpoint da API Get Organizations:

https://apigee.googleapis.com/v1/organizations/org_name

O exemplo a seguir recebe detalhes sobre a organização $ORG_NAME: neste exemplo, $ORG_NAME é definido como "apigee-example".

curl -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"

A resposta à sua solicitação contém detalhes sobre a organização especificada no formato JSON.

O exemplo a seguir mostra uma resposta com detalhes sobre a organização apigee-example:

{
  "name": "apigee-example",
  "displayName": "apigee-example-org",
  "description": "Apigee Example Org",
  "createdAt": "1626237148461",
  "lastModifiedAt": "1626237149384",
  "properties": {
    "property": [
      {
        "name": "features.hybrid.enabled",
        "value": "true"
      },
      {
        "name": "features.mart.connect.enabled",
        "value": "true"
      }
    ]
  },
  "analyticsRegion": "us-west1",
  "runtimeType": "HYBRID",
  "subscriptionType": "TRIAL",
  "projectId": "apigee-example",
  "state": "ACTIVE",
  "billingType": "EVALUATION",
  "expiresAt": "1631421073171",
  "addonsConfig": {
    "advancedApiOpsConfig": {},
    "integrationConfig": {},
    "monetizationConfig": {}
  }
}

Listar organizações

Para ver uma lista de todas as organizações às quais sua conta do Google Cloud tem acesso:

Envie uma solicitação GET (sem corpo) para o seguinte endpoint da API List Organizations:

https://apigee.googleapis.com/v1/organizations

Exemplo:

curl -H "Authorization: Bearer $TOKEN" "https://apigee.googleapis.com/v1/organizations"

A resposta à solicitação contém uma matriz de todas as organizações habilitadas para o sistema híbrido que você pode acessar no formato JSON.

O exemplo a seguir mostra uma resposta com uma única organização, apigee-example:

{
  "organizations": [
    {
      "organization": "apigee-example",
      "projectIds": [
        "apigee-example"
      ]
    },
    {
      "organization": "apigee-example-2",
      "projectIds": [
        "apigee-example-2"
      ]
    }
  ]
}

Como solucionar problemas na criação da organização

Ao criar uma organização com a API Create Organizations, você talvez receba uma resposta de erro. As respostas têm a seguinte aparência:

{
  "error": {
    "code": HTTP_error_code,
    "message": "short_error_message",
    "status": "high_level_error_type",
    "details": [
      {
        "@type": "specific_error_type",
        "detail": "expanded_error_description"
      }
    ]
  }
}

O exemplo a seguir mostra uma resposta a um erro comum. O ID da organização contém caracteres ilegais (caracteres maiúsculos não são permitidos nos IDs da organização):

{
  "error": {
    "code": 400,
    "message": "invalid Organization ID \"MY-ORG\": \"MY-ORG\" is an invalid Organization ID",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "",
        "detail": "[ORIGINAL ERROR] generic::invalid_argument: invalid Organization ID \"MY-ORG\":
          \"My-ORG\" is an invalid Organization ID [google.rpc.error_details_ext]
          { message: \"invalid Organization ID \\\"MY-ORG\\\": \\\"MY-ORG\\\" is an invalid
          Organization ID\" }"
      }
    ]
  }
}

Nesse caso, você tem a opção de renomear a organização com letras minúsculas e reenviar sua solicitação.

A tabela a seguir lista os erros que você pode receber e as possíveis resoluções ao tentar criar uma nova organização:

Código de erro HTTP	Erro HTTP	Descrição
`400`	`Invalid JSON payload received`	A estrutura dos dados na solicitação contém um erro de sintaxe ou o caminho para o endpoint está incorreto.
`400`	`Invalid organization ID`	O ID da organização solicitado não pode conter letras maiúsculas ou quaisquer caracteres especiais diferentes de hífens. Ele precisa conter apenas letras minúsculas, números e/ou hífens. Ele pode ter até um máximo de 32 caracteres.
`400`	`Unsupported analytics region`	Você não especificou o valor de `analyticsRegion` no corpo da solicitação ou o valor especificado não é uma das opções válidas.
`400`	`Does not have an Apigee entitlement`	Seu projeto do Google Cloud (criado na Etapa 2: criar um projeto do Google Cloud) ainda não foi ativado como híbrida. Isso pode indicar um problema com seu faturamento ou algum outro erro relacionado à sua conta do Google Cloud. Para mais informações, entre em contato com a equipe de vendas da Apigee.
`401`	`Request had invalid authentication credentials`	Seu token de autenticação `gcloud` está incorreto ou desatualizado ou não foi incluído na solicitação. Gere um novo token e reenvie o endereço.
`403`	`Permission denied on resource project project_ID`	Você pode ter enviado uma solicitação que continha um caminho ou ID de projeto incorreto.
`403`	`Unable to retrieve project information`	A organização ainda não foi criada ou provisionada. É possível emitir uma solicitação à API Operations para verificar o status da operação de longa duração, conforme descrito na etapa 5.
`409`	`Organization already exists`	Você tentou criar mais de uma organização para o projeto do Google Cloud. Você só pode criar uma organização por projeto.
`409`	`Org proposed_org_name already exists`	Você tentou criar uma organização que tem o mesmo ID que uma que já existe. Os IDs de organização precisam ser exclusivos em todos os clientes híbridos. Reenviar com um novo ID da organização proposto. Por exemplo, anexe um valor numérico ao final do ID anterior que você tentou.

1 2 3 4 (A SEGUIR) Etapa 5: criar um grupo de ambiente