Provisionar o hub da API na linha de comando

Esta página se aplica à Apigee e à Apigee híbrida.

Este documento explica como provisionar o hub de API na linha de comando. Se você preferir provisionar o hub de APIs usando a interface do assistente, consulte Provisionar o hub de APIs no console do Cloud.

Antes de começar

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Make sure that you have the following role or roles on the project:

   • roles/serviceusage.serviceUsageAdmin
   • roles/cloudkms.admin
   • roles/apihub.provisioningAdmin
   • roles/resourcemanager.projectIamAdmin

   Check for the roles

   1. In the Google Cloud console, go to the IAM page.

      Go to IAM
   2. Select the project.

   3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

   4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

   Grant the roles

   1. In the Google Cloud console, go to the IAM page.

      Acessar o IAM
   2. Selecionar um projeto.
   3. Clique em CONCEDER ACESSO.

   4. No campo Novos principais, insira seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.

   5. Na lista Selecionar um papel, escolha um.
   6. Para conceder outros papéis, clique em Adicionar outro papel e adicione cada papel adicional.
   7. Clique em Salvar.

   Resumo das etapas

   As etapas de provisionamento são as seguintes:

   1. Etapa 1: ativar APIs É necessário ativar um conjunto de APIs do Google Cloud para que o hub de APIs da Apigee funcione.
   2. Etapa 2: criar a identidade do serviço do hub da API Apigee. A identidade do serviço permite que a instância do hub de APIs chame as APIs do Google Cloud necessárias para realizar as operações.
   3. Etapa 3: Configurar criptografia. Você pode escolher se quer usar uma abordagem de Google-owned and Google-managed encryption key (GMEK) ou de chave de criptografia gerenciada pelo cliente (CMEK) para criptografar e descriptografar os dados da API em repouso. Consulte Comparação entre CMEK e Google-owned and Google-managed encryption keysde propriedade do Google.
   4. Etapa 4: criar a instância do hub de API. Para concluir, registre o projeto host e crie a instância do hub da API.

   Etapas de provisionamento

   Verifique se você atendeu aos pré-requisitos descritos em Antes de começar.

   Etapa 1: ativar as APIs

   Para provisionar o hub de API, ative as seguintes APIs no projeto Google Cloud :

   Permissões exigidas para a tarefa

   É possível conceder ao provisionador do hub de API da Apigee um papel predefinido que inclua as permissões necessárias para concluir essa tarefa ou conceder permissões mais refinadas para fornecer o privilégio mínimo necessário. Consulte Papéis predefinidos e Permissões de ativação de API.

   1. Ative as APIs do Google Cloud necessárias executando o seguinte comando services enable:

      gcloud services enable apihub.googleapis.com \
          cloudkms.googleapis.com --project=YOUR_PROJECT_ID

      em que YOUR_PROJECT_ID é o ID do projeto do Cloud que você criou em Antes de começar.

   Etapa 2: criar a identidade do serviço do hub de API da Apigee

   A identidade do serviço permite que a instância do hub de APIs chame as APIs do Google Cloud necessárias para realizar as operações.

   1. Crie a identidade do serviço:

      gcloud beta services identity create --service=apihub.googleapis.com \
        --project=YOUR_PROJECT_ID

      em que YOUR_PROJECT_ID é o ID do projeto do Cloud que você criou em Antes de começar.

   2. Verifique se o agente foi criado com sucesso. A resposta inclui o nome do agente no seguinte formato: [e-mail]. Exemplo:

      Service identity created: [e-mail]

      Você vai precisar usar essa identidade de serviço em uma etapa posterior.

   Etapa 3: configurar a criptografia

   Nesta etapa, você configura como a criptografia de dados na instância do hub da API é gerenciada. É possível usar uma Google-owned and Google-managed encryption key (GMEK) ou criar sua própria chave de criptografia gerenciada pelo cliente (CMEK). Consulte Comparação da CMEK e do Google-owned and Google-managed encryption keysdo Google.

   Etapas da CMEK

   Siga estas etapas se quiser usar a CMEK para criptografia de dados:

   1. Crie um keyring e uma chave de criptografia do banco de dados do ambiente de execução. Se quiser, você pode usar uma chave e um chaveiro CMEK atuais. A chave precisa ser criada no mesmo local em que você planeja criar a instância do hub da API.

      1. Crie um novo keyring:

         O nome do keyring precisa ser exclusivo para sua organização. Se você criar uma segunda ou uma região subsequente, o nome não poderá ser igual ao de qualquer outro keyring.

         gcloud kms keyrings create KEY_RING_NAME \
           --location KEY_RING_LOCATION --project YOUR_PROJECT_ID

         Em que:

         • KEY_RING_NAME: o nome do keyring a ser criado.
         • KEY_RING_LOCATION: o local físico do keyring. Esse local precisa ser o mesmo que você planeja usar para a instância do hub de API que vai criar em uma etapa posterior. Use um destes locais compatíveis:

           Descrição da região	Nome da região
           Iowa	us-central1
           Norte da Virgínia	us-east4
           Oregon	us-west1
           Bélgica	europe-west1
           Londres	europe-west2
           Singapura	asia-southeast1
           Mumbai	asia-south1
           São Paulo	southamerica-east1
           Sydney	australia-southeast1

         • YOUR_PROJECT_ID: o ID do projeto do Cloud que você criou em Antes de começar.

      2. Crie a chave de criptografia e adicione ao keyring:

         gcloud kms keys create KEY_NAME \
           --keyring KEY_RING_NAME \
           --location KEY_LOCATION \
           --purpose "encryption" \
           --project YOUR_PROJECT_ID

         Em que:

         • KEY_NAME: o nome da chave do banco de dados que você está criando.
         • KEY_RING_NAME: o nome do keyring que você acabou de criar.
         • KEY_LOCATION: o local físico da chave. Use o mesmo local usado para criar o keyring.

      3. Consiga o ID da chave:

         gcloud kms keys list \
           --location=KEY_LOCATION \
           --keyring=KEY_RING_NAME \
           --project=YOUR_PROJECT_ID

         O ID da chave tem a seguinte sintaxe (semelhante a um caminho de arquivo). Mantenha este ID da chave, porque ele será necessário em uma etapa posterior:

         projects/YOUR_PROJECT_ID/locations/KEY_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME

      4. Conceda acesso ao agente de serviço da Apigee para usar a nova chave:

         gcloud kms keys add-iam-policy-binding KEY_NAME \
           --location KEY_LOCATION \
           --keyring KEY_RING_NAME \
           --member serviceAccount:SERVICE_ACCOUNT \
           --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
           --project YOUR_PROJECT_ID

         Em que SERVICE_ACCOUNT é o ID da conta de serviço criada na Etapa 2. O ID vai ser parecido com este: [e-mail].

         Esse comando vincula a chave ao agente de serviço do hub de API da Apigee.

         Após a conclusão dessa solicitação, gcloud responde com algo semelhante ao seguinte:

         Updated IAM policy for key [runtime].
         bindings:
         - members:
           - serviceAccount:[e-mail]
           role: roles/cloudkms.cryptoKeyEncrypterDecrypter
         etag: BwWqgEuCuwk=
         version: 1

         Se você receber um erro como este:

         INVALID_ARGUMENT: Role roles/cloudkms.cryptokms.cryptoKeyEncrypterDecrypter is not supported for this resource.

         Verifique se você usou o número do projeto e não o nome do projeto no endereço de e-mail da conta de serviço.

   Etapas do GMEK

   Se você quiser usar a GMEK para criptografia de dados, vá para a próxima etapa, Etapa 4: criar a instância do hub da API. Nenhuma outra configuração de chave é necessária.

   Etapa 4: criar a instância do hub da API

   Um projeto host é o Google Cloud projeto em que você vai provisionar o hub de API da Apigee. Só é possível provisionar uma instância do hub de API por projeto host.

   1. Registre o projeto host:

      curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" -d '{
        "gcpProject": "projects/YOUR_PROJECT_ID"
        }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/hostProjectRegistrations?host_project_registration_id=HOST_ID

      Em que:

      • YOUR_PROJECT_ID: o ID do projeto do Cloud que você criou em Antes de começar.
      • PROJECT_LOCATION: o local físico (região) em que você quer hospedar a instância do hub da API da Apigee. Use o mesmo local usado para criar a chave e o keyring do CMEK. As regiões com suporte são:

        Descrição da região	Nome da região
        Iowa	us-central1
        Norte da Virgínia	us-east4
        Oregon	us-west1
        Bélgica	europe-west1
        Londres	europe-west2
        Singapura	asia-southeast1
        Mumbai	asia-south1
        São Paulo	southamerica-east1
        Sydney	australia-southeast1

      • HOST_ID: o nome do projeto host.
   2. Crie a instância do hub de API:

      Com a CMEK

      Se você usou a CMEK para criptografia de dados, execute o seguinte comando:

      curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" -d '{
        "config":{
          "cmekKeyName":"KEY_NAME",
          "vertexLocation":"VERTEX_LOCATION",
          "encryptionType":"CMEK"
          }
        }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/apiHubInstances?api_hub_instance_id=INSTANCE_ID

      Em que:

      • KEY_NAME (obrigatório): o nome totalmente qualificado da chave CMEK. Esse nome foi retornado quando a chave foi criada. Por exemplo, projects/YOUR_PROJECT_ID/locations/HOST_LOCATION/hostProjectRegistrations/HOST_ID.
      • VERTEX_LOCATION (opcional): especifica o local multirregional em que os dados de pesquisa baseados na Vertex AI, que são os dados associados ao recurso Pesquisa semântica do hub de APIs, serão armazenados. É possível usar us ou eu para esse valor. Se você não quiser usar nenhuma dessas multirregiões, desative a pesquisa semântica omitindo esse parâmetro.
      • encryptionType (obrigatório) Você precisa usar CMEK.
      • YOUR_PROJECT_ID é o ID do projeto do Cloud que você criou em Antes de começar.
      • PROJECT_LOCATION: use o mesmo local usado para registrar o projeto host.
      • INSTANCE_ID: o nome da instância do hub da API. Esse valor precisa ter de 4 a 40 caracteres, e os caracteres válidos são /[a-z][A-Z][0-9]-_/.

      Com a GMEK

      Se você estiver usando a GMEK para criptografia de dados, execute o seguinte comando:

      curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" -d '{
        "config":{
          "vertexLocation":"VERTEX_LOCATION",
          "encryptionType":"GMEK"
          }
        }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/apiHubInstances?api_hub_instance_id=INSTANCE_ID

      Em que:

      • VERTEX_LOCATION (opcional): especifica o local multirregional em que os dados de pesquisa baseados na Vertex AI, que são os dados associados ao recurso Pesquisa semântica do hub de APIs, serão armazenados. É possível usar us ou eu para esse valor. Se você não quiser usar nenhuma dessas multirregiões, desative a pesquisa semântica omitindo esse parâmetro.
      • encryptionType precisa ser GMEK. Se você não informar um tipo de criptografia, o GMEK será o padrão.
      • YOUR_PROJECT_ID é o ID do projeto do Cloud que você criou em Antes de começar.
      • PROJECT_LOCATION: use o mesmo local usado para registrar o projeto host.
      • INSTANCE_ID: o nome da instância do hub da API. Esse valor precisa ter de 4 a 40 caracteres, e os caracteres válidos são /[a-z][A-Z][0-9]-_/.

   Etapa 5: criar um anexo de projeto de ambiente de execução (opcional)

   Se você provisionou o hub de API em um projeto com proxies da Apigee, siga esta etapa opcional para registrar automaticamente os proxies no hub de API.

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" \
     https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/runtimeProjectAttachments?runtimeProjectAttachmentId=YOUR_PROJECT_ID

   Em que:

   • YOUR_PROJECT_ID é o ID do projeto do Cloud que você criou em Antes de começar.
   • PROJECT_LOCATION: use o mesmo local usado para registrar o projeto host.

   A seguir

   Agora você já pode começar a usar o hub de API:

   • Revise os papéis e permissões necessários para usar o Hub da API
   • Configure os atributos do hub de API:
     • Gerenciar atributos
     • Guia de início rápido: criar e editar atributos
   • Registrar um recurso de API:
     • Gerenciar recursos de API
     • Guia de início rápido: registrar uma API
   • Adicione uma versão da API:
     • Visão geral das versões
     • Guia de início rápido: criar uma versão da API